So you understand your user documentation project and you’ve specced it out. Now you’re ready to write. Here’s some tips to help you on your way. This article isn’t about
actual writing itself; it’s about things which go along with writing. (For information on writing online help, see www.divinewrite.com/helpfulhelp.htm.) NOTE: This is final article in a series of three outlining key elements of a good user documentation process. (To read first and second articles in this series, go to http://www.divinewrite.com/docoprocess1.htm and http://www.divinewrite.com/docoprocess2.htm.)
Indexing
Index keywords should be defined while topic is being written. At this time, subject matter is clear in author’s mind, and they are very conversant with all of intricate details. Indexing during writing stage also means that your keywords are reviewed as part of draft process. Some authoring tools don’t really facilitate this kind of approach particularly well (e.g., some don’t allow multiple author access to files needed for indexing), but at least keywords should be listed at end of each draft. (Depending on authoring tool, this may actually be easier for reviewers, anyway.) TIP: For further information on indexing, see The Art of Indexing (1994) by Bonura.
User documentation reviews
To ensure that your user documentation is technically correct and readable, you need to get it reviewed by an intelligent selection of people. For a software project, your review list should include a subject matter expert (generally programmer), software architect, perhaps project manager, and another writer. The review requirements will vary with each draft, so your reviewers and review procedures should be documented in your work pracs.
Testing your user documentation
Testing can be performed at a number of levels:
•Each writer should test their own user documentation by following it to use product. But remember, this kind of testing isn’t very powerful, because there’s a tendency for writers to follow instructions as they think they’ve written them, not as they’ve actually written them. •The second level is for testing to be performed by other writers… as part of peer review. •The third level is for testing department to do formal testing on user documentation. This type of testing doesn’t often happen, but it’s good to try to get it happening. •The fourth level is/should be conducted as part of Beta testing (see Managing Your Documentation Projects by Hackos (1994), pp.452-453).
No matter what level of testing you use, it should be designed to ensure that tasks documented are true to product, and that any online help functions correctly. For user documentation to pass testing, it needs to satisfy goals you specified in earlier stages of project.
Localising your user documentation
Although localisation is often considered a post-writing activity, it’s best to do it as part of writing stage. The exact timing may vary project to project, but a good rule of thumb is to get translators working on second drafts (but only if you’re not expecting many changes to draft). TIP: Most translators will probably prefer to work on a sizable piece of user documentation, rather than individual topics sent to them piece-meal, so you should wait ‘til you have something of a respectable size to send them – perhaps a whole subject area, as opposed to a single topic.
