Three Simple Mistakes Non-Technical Writers Make
If you ask someone who has never written technical documentation before to describe a procedure, chances are he or she will give you a document that looks as follows:
- It completely omits numbered steps.
- Each paragraph or line is followed by a full-size screenshot that takes up half the page.
- Quotation marks surround various names somewhat at random.
Fortunately these mistakes are easy to fix.
When describing a sequence, number each step. Keep the task about 5-10 steps long. If the steps don't need to be performed in sequence, use bullets instead. The use of steps helps the reader follow along more easily. If you have a long procedure (15-30 steps), break it into multiple tasks.
Only use screenshots when they are necessary for clarification. If a procedure is easy to follow without a screenshot, don't add unnecessary bulk to the procedure by adding the screenshot. When you do add screenshots, use partial screenshots that focus on the area you're highlighting. In general, keep the task as concise and light as possible without confusing the reader.
When you tell a reader to click a button or select a link, bold the direct object. For example, Click the Print button. Quotation marks often set off words and give them a different meaning. For example, if I wrote, Oh yes, the show was "great" last night, you'd know the show was terrible. Even without this meaning, it's just better practice to bold direct objects — it helps scanning and allows readers to quickly predict what they're supposed to click or select.
I haven't said anything about accuracy or the use of styles, but these are also major omissions newbies make. Exactly how accurate are the steps? Chances are a review of the procedure will show some steps were left out, some buttons or links were misnamed, and overall it may be hard to follow.
Is the text structured with specific styles? Probably not. Many new technical writers prefer the inline formatting toolbar. While you may get by with a short document using inline formatting, it's not good practice and will cost you more time and frustrate you in the long run. Here's a handout (.pdf) on using styles in Microsoft Word by Pam Treme, a colleague in the Suncoast chapter.
What are some common problems you see in technical writing by beginners?
photo from flickr.com
About Tom Johnson
I'm a technical writer based in the California San Francisco Bay area. In this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, visual communication, information architecture, writing techniques, plain language, tech comm careers, and more. Check out simplifying complexity and API documentation for some deep dives into these topics. If you're a technical writer and want to keep on top of the latest trends in the field, be sure to subscribe to email updates. You can also learn more about me or contact me.