Enterprise Software

Four tips for designing documentation

Does the thought of creating technical documentation make you cringe? Use these four technical writing tips to save time and increase clarity when designing documentation for your customers and coworkers.


How do you recover a damaged database? In what order should the servers be brought back up after a controlled shutdown? How do you look up a customer ID in the system?

If the answers to those questions aren't documented somewhere, they're probably floating around inside the heads of the people in the IT department. If you've been putting off creating support documents, here are some tips to jump-start the process.

Don't write a novel when a punch list will do
In many cases, the best tech support documentation is a one-page set of instructions with checklists. Let's consider how to document the answer to the question: In what order should the servers be brought back up after a controlled shutdown?

A coworker, a network engineer, wrote a document to guide the network operations center technicians through the process of restarting "the system." The network engineer told me, "They're having the hardest time with my instructions, and I don't understand why."

One glance at the document suggested the reason: It was five pages long, full of densely packed paragraphs of instructions. When you looked closely at the text, the nuggets of useful instruction were buried under layers of details. While those details are useful information, they can get in the way when you're just trying to get through a standard operating procedure.

I suggested we try to turn the whole thing into a one-page punch list. To that end, we:
  • Read the five-page document aloud, editing it to 20 items, each no more than a couple of sentences long.
  • Used Word's custom bullets to format the whole list with check boxes at the beginning of each item.
  • Added space at the top for technicians to date and initial the form.

The technicians report fewer miscues since they started using the punch list instead of the long version. The long version didn't go away; it's published in the network operations center and on the intranet, so technicians can refer to it when they need it.

Download TechRepublic's most popular punch list, "The ultimate preventive maintenance checklist."

Write in sets of five
If you're writing a how-to manual for customers or coworkers to use, you can wear out your reader with series of 10, 20, or 30 numbered instructions at a time. When the subject matter requires lots of steps, try to organize them into groups of no more than five instructions for a particular task.

Before you organize your groups, however, you must trim the number of instructions overall. One of the most common reasons for bloated how-to documents is putting instructions like "Click OK" or "Press [Enter]" on lines by themselves. To lower the number of instructions, consolidate rudimentary steps like "Click OK" into the previous instruction.

For example, consider what purpose is served in this case by putting the second instruction on a separate line:
1. Type a name for the file.
2. Click OK.

It's easy to consolidate those two steps into one:
1. Type a name for the file and then click OK.

In addition to looking for opportunities to consolidate two or more instructions, keep an eye out for sets of instruction that logically go together. Then, label those sets accordingly.

For example, to guide a new employee through starting a PC, logging on has little to do with launching Word or checking e-mail. So you might organize groups of instructions by using a short description of the task at hand to label the sets of related instructions. For instance, the first set of instructions in "how to use computers at ABC Inc." might look like this:
Computer and login
1. Locate power switches and turn on.
2. Wait for login screen to appear.
3. Enter your ID and press [Tab].
4. Enter your password and press [Enter] or click OK.

There will of course be times when you must write more than five instructions for a given task. But remember, the more complicated the instructions the more likely your users will become lost.

Polish your screen shot technique
Recently, a friend called to tell me how mad he was about a support document created by one of the "accounting people" in his firm. "It was 20 pages of print screens and almost no text," he said. "The Web-dev guys were making fun of me because I was standing at the printer so long, and it did me absolutely no good. It didn't teach me how to use the new accounting interface."

The accounting person apparently discovered [PrintScreen] and thought he or she was creating a technical writing masterpiece. But while a picture is worth a thousand words, you sometimes need an extra 50 or so to explain what the picture means to your audience.

Here are some Word tricks for sprucing up your screen shots:
  • Learn to crop your images. To do so, display the Picture toolbar, click the Crop tool, mouse over the border handles, and then click-and-drag to crop the image. Nothing screams "amateur tech writer" like a screen shot of the entire Windows desktop.
  • Use [Alt][PrintScreen], which captures only the active window, not the entire Windows desktop.
  • Use the Drawing toolbar's Text box tool to draw a box right on top of your screen shot. Make sure to use a white fill for the text box, so it will be visible.
  • Draw arrows and circles to draw attention to important parts of your screen shot.
  • Group the screen shot and its arrows, circles, and text boxes, by holding down [Shift] while you click on each object; then, right-click on the selection and choose Grouping and then Group. Doing so prevents those objects from drifting apart when you edit the text around them.

If you need more screen-capturing power than available through [PrintScreen], try SnagIt. (For a review of SnagIt, see “Create figures for your training materials with SnagIt.”)

Know your audience
This tip is perhaps the most important of all. If you're asked to create a how-to manual or a technical document for end users in your organization, go meet the people who will be using your document.

Here are some questions to ask while you're there:
  • What's the hardest thing to remember about using [your system]?
  • What do you like best about the system?
  • Do you use online help, or do you prefer to have a printed manual?

Look at everyone's bulletin boards and computer workstations. If you see punch lists, lists of keyboard shortcuts, and other cheat sheets, make sure you create similar lists for this audience when you write the new documents.

In every group of users, there'll be at least one whose motto is, "I don't need no stinkin' manual." Write with those people in mind, because when they eventually must refer to your documentation, it had better be easy to follow!

Documentation details
What tips would you add to Jeff Davis’ ideas about developing documentation for IT processes? Post a note below or send Jeff an e-mail.

 

Editor's Picks

Free Newsletters, In your Inbox