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
I'd Rather Be Writing Newsletter
Get new posts delivered straight to your inbox.
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 communication — Swagger, agile, trends, learning, plain language, quick reference guides, tech comm careers, academics, and more. I'm interested in simplifying complexity, API documentation, visual communication, information architecture and findability, and more. If you're a technical writer of any kind (progressional, transitioning, student), be sure to subscribe to email updates using the form above. You can learn more about me here. You can also contact me with questions.