If you’ve ever had a conversation with me that lasted longer than a few minutes, you know the one thing that will keep me talking is end-user documentation. Whether you are writing documentation for your implementation of a CMS, a migration from one application to another, or simple instructions on using a Web form or Web application, how you write the documentation is critical. Yet so many of us wing it.
I like to compare writing end-user documentation to fluency in a second language: Most of us pick it up by immersing ourselves in the culture. We read technical documentation, and from what we learn from the “native” documenters, we use in our own writing. But for grammar nerds like myself (a former English and Communications teacher), we realize there are rules governing this language—a special syntax, it’s own punctuation, and more.
I was recently invited to speak about documentation to a documentation team for Penn State’s implementation of ANGEL. Here is just some of the advice I shared:
1. Document the steps or actions in order.
This one seems like a no-brainer. However when we construct sentences in everyday English, it’s easy to rearrange a prepositional phrase out of sequence because we listen to instructions completely before acting on them. For example, “Select Print under the File menu.” When people read documentation, they are trying to act on it as they read, so order is very important. We need to rework our instructions to reflect that, eg. “Under File, select Print.”
2. Document every action.
As superusers, we take for granted the intermediate steps, like clicking Next on a wizard. Even when we encounter something new, we are more prone to just taking a guess at what to do. Not every user is comfortable with making that leap of faith. Good documentation is like getting directions to someone’s house: you need to know what do expect at turn—maybe even every intersection—so that you know you are not lost.
3. Answer three questions with every step: Where am I? What should I do? What will happen?
Imagine if you had these questions answer for driving directions: “At the corner of 51st Street and 4th Avenue, turn right. You should see a park.” Shouldn’t all instructions be so explicit? “Under the File menu, choose Save As… The Save As dialogue box will appear.”
4. Keep the steps short and simple.
People don’t read documentation word-for-word; they scan it. Provide them with a single step at a time. When describing a path through a menu, replace prepositions with right arrows (→) to facilitate scanning. For example, which of the following is the easiest to scan:
- On the Format menu, select Alignment and click Left.
- Select Format, Alignment, Left.
- Select Format→Alignment→Left.
5. Use the language that the tool uses, but avoid jargon.
End-user will take what you document very literally, so pay attention to whether or not the application uses “OK”, “Save” or “Close”. If you must use a new term with which your audience may not be familiar (eg. “Scaffolding”, “Cascade”, “SSL”, etc.), make sure you define it. Be especially wary of how you use unfamiliar terms in your headers as their search terms might include different language entirely. For example, “Activating a Page” versus “How Do I Publish a Page”.
6. Don’t assume your audience is reading your documentation from beginning to end.
When was the last time you curled up with an entire manual and read it cover to cover? Your end-users won’t do this, especially with documentation on the Web. Make sure you treat each page of documentation—even each anchored section—as if your audience is approaching you material for the very first time. Define terms again and link to related content to provide your audience with some context.
Good recommendations that apply to other kinds of writing as well. Any sort of explanatory writing should benefit from clear, explicit writing. It’s all about considering the audience’s needs, right?