Three Simple Mistakes Non-Technical Writers Make

by Tom Johnson on Jul 27, 2007
categories: technical-writing

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.

Steps

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.

Screenshots

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.

Quotation Marks

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.

Other Characteristics

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