Be Consistent

Another important part to technical writing is being consistent in the way you word and style directions. Having a style guide that you follow will help you immensely.

Here is a generic group of steps:

  1. In the top menu bar, click FILE > New.
  2. Add and edit your content.
  3. Click on File -> Save As in the navigation.
  4. Name your file and choose the location where it should be saved.
  5. Start another file by clicking New in the File menu.
  6. Type something and write some content.
  7. Up at the top click on File → Save As.
  8. In the typing box where it says “File Name” give it a title, then click the Save button.
  9. Quit the application.

Those instructions above make my want to cry.

Do you see the ways that the directions to navigate are all different? (1, 3, 5, 7)

FILE > New
File -> Save As
New in the File menu
File → Save As

Not only are the styles different, but so are the words indicating the method.

In the top menu bar, click…
Click on… in the navigation
by clicking … in the … menu
Up at the top click on …

You can find your own style through:

  1. Practice – write more!
  2. Reading – read more! Pick up some instruction books at the book store. Browse through some online product guides. Good documentation is not just about the words, it is everything from the colors, images, instruction style, and thoroughness involved.
  3. Teaching – see what instruction styles work better than others. Use your teaching opportunities to say your instructions aloud and see if they stick to your audience. If you see blank faces and no comprehension, try wording it a different way and watch for the “aha!” moment when they get it.
  4. Communicating – talk with coworkers to build your style guide. If you get your coworkers to care about style guides, chances are they may use them as well.
  5. Iterating – nothing is perfect the first time, but you have to start somewhere. Write it. Improve upon it.

Published by Andrea Lee Bishop

Andrea (pronounced On-dree-ah) leads Automattic's Support Leads and works in hiring. She's a fixer, traveler, mom, math geek, aspiring-polyglot, musician, and coffee lover.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: