Skip to main content
Opinion

The Golden Rule of technical writing

I stumbled upon a list of tips for technical writers, and I was glad to see tip 7:

Understand Your Target Audience. Write and revise your content according to how your target audience thinks and understands things. Getting into their heads–knowing how their minds process information, how they might react, what they feel is important–allows you to customize your content to tailor-fit their needs.

I would put that tip at the top of the list, but that’s a quibble.

Sarah and I mention the topic of audience a lot in our Technical Writing 101 book; I think it is the most important thing for writers to remember as they create content. You can have an elegant XML-based publishing system that generates all sorts of output with the push of a button, but if your information doesn’t address the needs of users, all the work put into the content and into the process itself is wasted.

That waste becomes even more acutely painful when a user abandons your information and finds helpful content on a blog, wiki, or forum. The contributors of that information probably don’t know (or even care) that they followed the Golden Rule of technical documentation: Audience, audience, audience.

Alan Pringle
October 6, 2008
Read More
DITA

An incomplete puzzle: DITA OT stylesheets

A recent post on the dita-users Yahoo group asked how to customize the DITA OT stylesheets in view of the fact that there isn’t much documentation available.

From my work customizing and otherwise perverting the DITA OT, I can sympathize with these frustrations. When I started investigating OT customizations, I found many well-crafted tutorials on how to customize and specialize the OT. These were a great starting point, but they only got me so far. In its current state, the documentation is an incomplete jigsaw puzzle; the trees and buildings are filled in nicely, but the sky is still waiting for someone with patience. (Block that metaphor!)

Because there is no documentation available at the individual template level, you need to reconsider the task at hand. I look on it as debugging, decoding, or sleuthing. With that in mind, I find the following to be very useful:

  • Find a good visual grep-like utility. I use AgentRansack, a free version of FileLocator Pro (it’s free and amazing). This enables me to locate all files that contain a particular class identifier. The visual aspect of the tool allows me to see the context quickly.
  • Use a programmer’s editor that supports XML and XSL. We use Oxygen. Not only does it help check validity and closes tags automatically, but it also provides a handy sidebar that lists the templates and their modes.
  • Liberally spread <xsl:comment> or <xsl:message> directives through the stylesheets you’re examining. That helps figure out where you are. Use <xsl:value-of> or <xsl:copy-of> to figure out what you’ve got.
  • Once you’ve figured out what happens in one of the OT templates, add comments. Now the next time you come back to it, you won’t waste time.

Probably the best form of documentation that the OT could provide here is additional comments in the stylesheets, particularly about the order of processing. I find I add many comments about where to find the template that handles nodes from an <xsl:apply-templates> directive.

One further note. On Tuesday, September 23, I’ll be presenting the third of our “Best Practices in Structured Authoring and Publishing” joint Webinar series with JustSystems. In this presentation I’ll describe a number of approaches you can use to customize DITA OT output. For more information, visit the JustSystems web site.

Simon Bate
September 5, 2008
Read More
DITA

The hidden costs of DITA

Originally published in STC Intercom, April 2008

DITA is a free, pre-made XML document structure. That statement can lead to a few erroneous assumptions: if it’s free, then it will cut down on costs, and if it’s pre-made, it will cut down on labor. There are several things to consider when choosing a DITA solution. Does your staff have the skills to author in a DITA environment? Will additional training be required? Does DITA even match your content model, and if it doesn’t, is it worth the effort to change?

Sarah’s conclusion? “DITA may be free, but it’s not cheap.”

Download the PDF (950 K)

Sarah O'Keefe
April 19, 2008
Read More
Conferences

WritersUA: DITA pilot techniques

Mark Wallis of IBM ISS on how to run a successful DITA pilot. Some great information in this presentation on how to reduce risks.

He recommends selecting your pilot project based on the following items:

  • Right timeframe — don’t choose the project that has an imminent release
  • Choose a manageable documentation set size
  • Reduce risk by avoiding the strongest (or most critical) product
  • Identify a product with a known need to improve the user experience

They had one person out of a group of twelve, a “senior in name only” writer, leave because of this transition.

The ideal team for a pilot will need cross-functional and complementary skills:

  • Project management skills
  • Tools and technology strengths
  • Product knowledge and understanding
  • Architecture and design skills
  • Editor for standards and styles

Some advice on planning your content. (And it’s worth noting here that these apply to good writing and topic-oriented content rather than to DITA tools.)

  • No autopilot writing
  • Don’t just migrate existing content; you’ll get trapped in old paradigms (this assumes that existing content does not fit the DITA topic paradigm)
  • Perform use case analysis and task analysis
  • Determine the critical scenarios to document
  • Focus on tasks; backfill supporting information as needed

Some interesting discussion of “task support clusters,” which include conceptual overviews, related tasks, deep concept, and reference information. (Michael Hughes did a presentation on this earlier today, which I unfortunately was not able to attend.)

They set up a DITA War Room in a small conference room and met at least daily (1.5 to 2 hours per day. Yikes). They set weekly goals and used small tasks to build momentum.

There was also heavy use of an internal wiki to put up initial “straw man” design, then revise, comment, and discuss.

Layering deliverables
Implementation deliverables were split out into smaller tasks, such as:

  • Creating topic files, links, and navigation
  • Testing links from code and navigation
  • Creating task and reference topics
  • Validating help against the user interface
  • Creating concept topics for principles, guidelines, and best practices (“deep concept”)
  • Validating content in the expert community

For the third time, he points out that they are no longer documenting how to use a check box, so I guess I’ll mention it.

Choosing the DITA toolset

Task Modeler (free) for building and managing ditamaps, defining relationships between topics, and creating skeleton topics (stub files).

DITA-compliant editor to edit your topics.

Compiler (part of open source toolkit). Compiler? What are they compiling? HTML Help? Oh. He just referred to Ant as a compiler. Ohhhhhkay.

Proof of concept

They picked a subset of the pilot to do the proof of concept.

The presenter’s boss is quoted as saying, “There’s no such thing as bad weather, only insufficient clothing.” I’m guessing that she’s never been to Minnesota in winter.

The objectives for the proof of concept:

  • Learn and evaluate tools
  • Address technical obstacles
  • Specify end-to-end requirements

They learned that deliverable formats matter because they must deliver several different formats.

Managing costs

Purchase toolsets only for pilot team.

After completing proof of concept (successfully!), invest in tools for the remaining writers.

Wiki

They used their wiki to capture conventions and guidelines.

Improving acceptance

They paid attention to the change management issues. He doesn’t mention it here, but I would assume that the combination of an acquisition by IBM plus the requirement to change the authoring environment could have caused significant angst. Their approach included presentations, wiki content, email discussions, and online training.

At the point of transition, DITA boot camp was offered.

They used collaborative walkthroughs, or reviews, to help standardize their content development. Interesting. This sounds as though it could be a) threatening and b) an unbelievable time sink. But just maybe it might also c) help improve the content.

Other lessons learned

Think more, write less. (Don’t document the obvious, don’t document common user interface convention, write only if you’re really adding value.)

Don’t squander your ignorance. (If something makes you stumble in the interface, that will probably also cause problems for your users, so capture it.)

The more structured your content, the easier the transition to DITA.

Documenting the obvious teaches readers to ignore your text, so don’t document the obvious.

The handouts are available here: http://www.writersua.com/ohc/suppmatl/

Sarah O'Keefe
March 19, 2008
Read More
Opinion

Content creation isn’t just for tech writers

We’ve seen an increase in the number of clients who need documentation processes that include input from part-time contributors (particularly engineers). XML-based workflows make it easier to handle this sort of input. Part-time contributors can enter their information into forms or can edit XML documents in an editor that doesn’t require them to know a thing about publishing tools.

UC Irvine seems to have picked up on this trend in collaboration: the school’s extension program just announced a technical writing class for engineers:

“This course is designed to provide students with writing skills tailored for the science and engineering fields and to correct common problems,” said Jessica Scully, M.J., instructor of the course. “It covers the importance of writing for a particular audience, and applies journalism skills to help students effectively create a focused and concise document.”

The benefits of such a program go beyond engineering. Improvement in the quality of developers’ writing would likely mean a reduction in the cost of creating a more unified voice in content (which in turn would lead to a smoother localization process). And last but not least, the end users (internal or external) would get better documentation.

This class could also help engineers gain an appreciation of the skill sets technical writers bring to an organization. That being said, it would be unfortunate if a company made the short-sighted mistake of thinking that sending engineers to a class like this would transform them into instant technical communicators.

Alan Pringle
February 27, 2008
Read More
XML

When is XML the wrong answer?

Originally published in STC Intercom, November 2007

XML can benefit a publishing workflow in many ways: improving content reuse, consistency, and potentially automating much of the process. That all sounds wonderful, but XML is not the logical answer for everyone.

Implementing a structured authoring solution requires a significant change from the familiar desktop publishing routine to new tools, technologies, and processes. Switching to XML is going to cost time and money. Depending on your needs, it may not be the most efficient solution.

Download the PDF PDF file (350 K)

Sarah O'Keefe
November 19, 2007
Read More
Conferences

tekom: Benefits for North American writers

My post about tekom generated some interesting comments, including this one, which I will address in pieces:

Thanks for this info. I’ve been lobbying my company to send me to Tekom for the last few years, unsuccessfully. I submitted 2 times for presentations but both were rejected. Our company is in Concord, Massachusetts, USA.
Could you discuss the benefits to North American writers attending such an international event. Are there things you learned there you will not learn anywhere else (business/tech stuff of course )

Interesting question.

Sarah O'Keefe
November 13, 2007
Read More
Opinion

The Age of … Expertise?

Over on O’Reilly’s Radar blog, Andy Oram has a fascinating article about the demise (!) of the Information Age and what will be next:

[T]he Information Age was surprisingly short. In an age of Wikipedia, powerful search engines, and forums loaded with insights from volunteers, information is truly becoming free (economically), and thus worth even less than agriculture or manufacturing. So what has replaced information as the source of value?The answer is expertise. Because most activities offering a good return on investment require some rule-breaking–some challenge to assumptions, some paradigm shift–everyone looks for experts who can manipulate current practice nimbly and see beyond current practice. We are all seeking guides and mentors.

What comes after the information age? (be sure to read the comments, too)

It’s an interesting idea, but I don’t think we’re getting away from the Information Age into the Expertise Age. After all, expertise is just a specialized (useful!) form of information.

In the comments, Tim O’Reilly points out that the real change is in how information is gathered and distributed with “the rise of new forms of computer mediated aggregators and new forms of collective curation and communication.”

I believe that we are still firmly in the Information Age because information has not yet become a commodity product. There is, however, clearly a shift happening in how information is created and delivered. I think it’s helpful to look at communication dimensions:

  • Traditional technical writing is one-to-many. One person/team writes, many people consume it.
  • Wikis are many-to-many. Many people write; many people use the information.
  • Mailing lists are many-to-one. Many people respond to one persons’ question.
  • Technical support is one-to-one. One person calls; one person responds.

Technical support is the most expensive option; it’s also often the most relevant. Technical writing is more efficient (because the answer to the question is provided just once), but also less personal and therefore less relevant.

Many technical writers are concerned about losing control over their content. For an example of the alarmist perspective, read Joanne Hackos’s recent article on wikis. Then, be sure to read Anne Gentle’s eponymous rebuttal on The Content Wrangler.

Keep in mind, though, that you can’t stop people from creating wikis, mailing lists, third-party books, forums, or anything else. You cannot control what people say about your products, and it’s possible that the “unauthorized” information will reach a bigger audience than the Official Documentation(tm). You can attempt to channel these energies into productive information, but our new information age is the Age of Uncontrolled Information.

Furthermore, the fact that people are turning to Google to find information says something deeply unflattering about product documentation, online help, and other user assistance. Why is a Google search more compelling than looking in the help?

Sarah O'Keefe
September 5, 2007
Read More
Conferences

TOC: Tim O’Reilly/Publishing 2.0

What do killer Internet applications have in common?

  • Information businesses (publishers??)
  • Software as a service
  • Internet as platform
  • Harnessing collective intelligence

Web 2.0: harness network effects to get better the more people use them.

  • Google: every time someone makes a web link, they contribute
  • eBay: critical mass of buyers and sellers hard for others to enter
  • amazon: 10M user reviews
  • craigslist: self-service classified ads, users do all the work
  • YouTube: viral distribution, user creation, user curation

Each of these companies is building a database whose values grows in proportion to the number of participants — a network-effective-driven data lock-in. (gulp)

Law of conversation of attractive profits

  • When attractive profits disappear at one stage the opportunity will usually emerge at an adjacent stage.
  • PCs used to be expensive. Software became expensive. Free precursor to rediscovery of value in some other form.

And thus, if digital content is becoming cheap, what’s next? What’s adjacent?

For publishers, the question is: where is value migrating to?

Asymmetric competition

  • craigslist has 18 employees, #7 site on the web (2005 numbers)
  • All others in top 10 have thousands of employees.

Curating user-generated content

  • The skill of writing is to create a context in which other people can think. — Edwin Schlossberg
  • The skill of programming is to create a context in which other people can share.

Collaborative authoring

What job does a book do? What is a book’s competition?

  • Harry Potter’s competitor is World of Warcraft
  • Encyclopedia Britannica — Wikipedia — Google
  • Books compete with information available online
  • Teaching/reference/edutainment

Search is most important benefit of content being online

“Piracy is progressive taxation”

  • Benefits the books at the bottom that would be lost
  • How to balance/manage a progressive taxation system
  • Gain more sales on the bottom end

DRM: “Like taking cat to a vet” (hold them very carefully and loosely!)

More options = happier users

Sarah O'Keefe
June 19, 2007
Read More
Conferences

TOC: Chris Anderson/Free: The economics of giving stuff away

Chris Anderson, editor-in-chief, Wired Magazine

The cost of things tend to fall to zero over time.

You can build business around giving things away:

  • Free samples
  • Skype, YouTube, free unlimited storage on Yahoo
  • Ad-supported media..product is free, make it back on ads
  • Free ice cream samples
  • Give away razor, sell blades
  • Gift economy/wikipedia, craigslist: people donate expertise/time for nonmonetary — attention, reputation, expression…never before “dignified” as an economy. There is an economy, just money is not the currency.

If marginal cost of reaching the N+1 customer is approaching zero, then treat the product as free and figure out how to sell something else.

The price of a magazine like Wired is arbirary; it bears no relationship to the actual cost of the magazine. The subscription price is intended to qualify your interest. Setting the price too low “devalues the product.”

Most music is free. “Free as in speech” — DRM is going away. “Free as in beer” — bands are experimenting with giving away music to market the live performances.

Games and movies would be free if not protected. They are locked down to enforce prices. Artificial barriers tend to fall over time. Already seeing ad-supported videogames. (neopets)

The shining exception: Books! They are not asymptotically approaching free. Books make sense. They provide the optimal way to read. The physical product is better than digital product…excellent battery life, screen resolution, portable, and it even looks good on your shelf. Easy to flip through.

If “free” is “the business model of the 21st century,” how could a book be free?

(This was preceded with a disclaimer that many of these options would be “offensive” to people in the audience.)

For his next book, Anderson wants to do the following:

  • Audiobook will be free with book (mp3) (free coupon in real book)
  • Will participate in book search, include Google
  • Considering an e-book locked to a specific reader for free
  • Unlocked e-book with advertising inserted
  • Book online with ads in the margins
  • As many sample chapters as publisher will accept

How could a physical book be free?

  • Sponsored book
  • Consultants give away books
  • Book with ads
  • Free rebate
  • Free to influentials/reviewers
  • Libraries have always had free books

Why do it?

  • Free book is marketing for the non-free thing
  • Book is marketing vehicle for celebrity
  • Can’t give away time
  • If free version is inferior, you give it away to market the better product
  • Use “free” to maximize reach to new influentials

Why aren’t more people doing free content?

  • Most people are not represented by a speaker’s bureau and can’t monetize fame
  • Online sample is not a compelling example of book (maybe for cookbook, probably not for novel)
  • No natural advertiser
  • Publisher opposition — publishers not in business of selling celebrity
  • Annoys the retailers
  • Fear and timidity/fear of cannibalization

The most critical point: The interests of the author and the publisher are critically misaligned. Publishers doesn’t benefit from speaking fees of consulting fees, only from book sales.

Sounds like an argument for self-publishing to me.

Sarah O'Keefe
June 19, 2007
Read More