Geeks With Blogs
Technical Writing by Mark Metcalfe, Publications Professional

I was asked about the method I use for documenting products, so I thought I'd blog about it.

Topic-based information is essential to today's computer user, whether using web software or shopping online. Most users use information to get "unstuck." Learning methodologies or reading the Great American Novel are for the student or the insomniac. Most experienced users can figure out how to use more intuitive software but hit the occasional snag in a process. Only then do they turn to the information set, Googling for an answer.

So how does this inform today's documentation efforts? The Darwin Information Typing Architecture (DITA) is based on three main types of information: Concept, Task, and Reference.

  • Concept - Why do I want to use this piece of software?
  • Task - How do I use this piece of software?
  • Reference - What does this software do?

When I begin a project, I often start with the reference material because most of the initial users of a new release are more experienced and established customers. They know their way around and need only to refer to the help to jog their memory about a switch on a command, or an unfamiliar parameter on a dialog box. If nothing else can be ready at release time (for whatever reason), make sure that the reference material is in place for the early adopters of the release.

The next thing I tackle are the tasks, because nominal users need sequential steps to accomplish something with the software. These tasks must be short and discrete topics, not long tutorials to teach (although tutorials have their place in technical documentation).

The last thing to be written are the introductions, summaries, and overviews (concepts) because this information is better understood after the reference and task material has been tested and documented. Using marketing collateral is helpful at this stage to present a company message of how the software is intended to be used.

My primary focus with documentation is for online use with ancillary builds of a manual. Topics can be strung together to form a book (printable PDF, usually) but that is my secondary focus. The primary focus of documenting topics is to give a user only the information he or she is looking for with references to related topics, if they want further information. Get them in, get them out, and get them on with their jobs.

One of the newer additions to this model is the ability to hide screen images in drop down text so experienced users can skim through a procedure quickly while nominal users can open a link to see what the screen should look like. (These are called "comfort images;" to see that what is on the screen is what is described in the help.) I can add as many comfort images to online topics as I like because the images are seen only when the user decides. However, I still have to decide which images get conditionalized to show up in the PDF book version, where I need to be more judicious of the images I supply.

Those are the basics. There is a lot more to creating useful documents.

Mark Metcalfe

Posted on Tuesday, September 14, 2010 4:36 PM | Back to top

Comments on this post: My Writing Methodology

# re: My Writing Methodology
Requesting Gravatar...
Well written, Mark. This sounds very similar to the approach I have followed as a consultant when teaching people how to use a newly installed software solution. They need to know how to go about their business first -- the other information can, and often does, wait until later.
Left by John W on Sep 17, 2010 6:47 PM

Your comment:
 (will show your gravatar)

Copyright © TechnicalWriting | Powered by: