Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,505

Stitcher radio

follow us in feedly

Want more tech comm blogs to follow? See my Tech Comm Collection of Blogs on Feedly.

Adobe Robohelp

Three Simple Mistakes Non-Technical Writers Make

Jul 27, 2007 • general

Common mistakesIf 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

follow us in feedly


Get new posts delivered straight to your inbox.

Subscriber count: 3,505

Powered by ZipRecruiter

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.