Heather Hall
We know you want to make your documentation as useful to clients as you can. To help you achieve this goal, TE SIG member Heather Hall (Austin, Texas) compiled a list of 10 common documentation mistakes and what you, as an editor, can do to correct them.
We’ve listed the top five mistakes here. For the others, access the “Corrigo Supplement” section of the TE SIG Website (www.stcsig.org/te/newsletter/ supplement).
1. Combining Multiple Procedures Into One
Mistake : Grouping into one procedure several tasks that users can perform in a window.
Solut ion: Create a separate procedure for each task.
3. Not Explaining Why to Perform a Procedure
Mistake : Not providing the purpose of performing procedures.
Solution: Provide an introductory paragraph before procedures. Exclude the introduction if the reason for performing the procedure is obvious. If users understand why they’re performing procedures, they can become more proficient in the software and even learn to troubleshoot their problems.
Correct
Prepare a Document Revision for Production
You must change the state of a document revision to “approved” to use it in production. Once you have approved the document revision, you can no longer change it.
1. Select Tools -> Sign-Off.
2. Click the Revision tab.
3. Select the document revision you want to use in production.
4. Click Approve.
Incorrect
Sign Off a Document
1. Select Tools -> Sign-Off.
2. Click the Revision tab.
3. Select the document revision whose state you want to change.
4. Do one of the following:
• To approve the document, click Approve.
• To activate the document, click Activate.
• To cancel the document, click Cancel.
• To retire the document, click Retire.
2. Not Making Procedural Titles Task-Oriented
Mistake: Using system terminology in procedural titles.
Solution: Make the titles of procedures task-oriented, using the user’s terminology. Only advanced users know the system’s terminology.
Correct
Index a Topic
Incorrect
Add a Marker to a Paragraph
Correct
Set the Column Width
Incorrect
Use the Width Doctor Component
3. Not Explaining Why to
Perform a Procedure
Mistake : Not providing the purpose of performing procedures.
Solution: Provide an introductory paragraph before procedures. Exclude the introduction if the reason for performing the procedure is obvious. If users understand why they’re performing procedures, they can become more proficient in the software and even learn to troubleshoot their problems.
Correct
Change the Viewing Resolution of a Scanned Image
Even fast computers tend to choke on TIFF files di splayed at a high resolution. The images are so big that it takes a few seconds for the screen to redraw as you scroll up or down the page. Full gray-scale TIFFs can be 500 kilobytes (KB) or more. To speed up the redraw, you can change the display of the TIFF file to a lower resolution.
Correct
Create a Control Algorithm
Create a control algorithm when you want to perform a calculation. Scripts run control algorithms. For example, a control algorithm could recommend settings for Synergy to use.
4. Putting Steps in
Paragraph Form
Mistake: Not using bulleted or numbered lists to clarify procedural steps.
Solution: Number procedural steps rather than lumping them into one paragraph. If the procedure consists of only one step, use a bullet rather than placing the step in a paragraph. Bullets or numbers signal users to perform one or more steps to make something happen.
Correct
1. Select File -> Open -> Control Algorithm.
2. In the Algorithm Documents list, select <NEW>.
3. In the Revisions list, select <NEW>, and then click OK.
4. In the Document Name field, type the name of the control algorithm.
Incorrect
Select File -> Open -> Control
Algor i thm. In the Algorithm
Documents list, select <NEW>. In the Revisions list, select <NEW>, and then click OK. In the Document Name field, type the name of the control algorithm.
Correct
• To spell check a topic, select Tools -> Spell Check Current Topic.
Incorrect
To spell check a topic, select Tools -> Spell Check Current Topic.
5. Putting Too Much
Information in a Step
Mistake: Placing explanations and multiple actions in a procedural step.
Solution: Put one action in each procedural step to let users quickly perform it. If the user must press Enter or click a button (for example, OK) after performing the action, include that next action in the same step as the main action. Place explanations in brief paragraphs below the action steps.
Correct
1. Select Tools -> References.
2. Click the Tree tab.
3. Select the Pecan check box, and then click OK.
Incorrect
1. Select Tools -> References. Click the Tree tab. Select the Pecan check box, and then click OK.
Correct
• To add photographs to a portfolio, type:
> addPhoto $fdr
where fdr is a folder that contains the photographs.
This places copies of the photographs in the portfolio and in the PhotoWand folder.
Incorrect
• To add photographs to a portfolio, type > addPhoto $fdr, where fdr is a folder that contains the photographs.
This places copies of the photographs in the portfolio and in the PhotoWand folder.
Don’t forget to check out the TE SIG Web site to learn about the other five common documentation errors.
Heather is a technical editor and senior technical writer at KLA-Tencor in Austin, Texas. She designs user interfaces and writes and edits online help and manuals.