Let standards guide your documentation

by Paul Baldwin | Dec 02, 2005 8:00:00 AM

Takeaway: When creating documentation, it's important to make sure that it's consistent. Otherwise, end users may be confused about what they're reading and what to expect. This article illustrates the importance of standards in documentation.

Regardless of your opinion toward The Wall Street Journal or The New York Times, each newspaper has its own indelible style. Beyond columnists, editorial slants, and front page layouts, the way design, formatting, and writing of each newspaper carries a strong identity, regardless of your political leanings. Even if the mastheads and bylines were absent from either paper, you would know what you're reading.

Of course, IT documentation doesn't aspire to the same goals as mainstream news publications. But if your users come across something that has been designed and written for your business, it should resemble--in layout, tone, or simple look and feel--the last piece of documentation they reviewed and the next "in-house" document they'll pick up.

When businesses decide to commit to documentation, standardization probably doesn't always rank high on what's considered important. After all, isn't telling your users how to solve a particular problem or explaining an application's new feature most important consideration? Why worry about anything else as long as the work is accurate?

Certainly, plenty of organizations take this approach. However, as more documents are produced, assuring your users that the content they're reading is accurate, up-to-date, and from a trusted source takes more than assumptions. Standards can help accomplish that.

Here are a few factors to consider including when planning a set of standards for your documentation:

The proper tone

Let's say your goal is to help users understand how a new version of an application affects them. But what else will your documentation communicate? Will your work guide users through the intricacies of the upgrade, or will it sternly warn them of possible pitfalls--or both? The tone of your documentation should be in line with the business expectations assigned to it.

In other words, if your intended users need a concise understanding of a new concept, make sure the documentation's tone makes that possible. Also, documentation is never the place for someone to try their skills as a comedy writer. There's nothing that says documentation should be boring, but entertainment isn't what you should be providing.

Write to the user's level of understanding

Whether it's used to train new hires or guide existing employees on a new application, your documentation should be written so that someone can do their job without requiring much prior knowledge of whatever system or application they're trying to learn. Often, documentation writers will assume far too much knowledge and understanding on the user's part. If you've ever put together documentation on something you're familiar with, it's easy to assume that the intended reader will know exactly what you're trying to communicate. Instead, write to a basic level of understanding for the role.

Write out acronyms on first reference

Few days hold as many lasting memories as the first few at a new job. You're faced with learning 1,000 different things to become proficient. Amid all this newness, fresh acronyms abound. In e-mail, conference calls, memos, and office talk, people will drop three-letter acronyms. Spell out an acronym the first time it appears in a document then follow it with the acronym. Whether you're writing about a Global Positioning System (GPS), an Internet Information Services (IIS), or a Content Management System (CMS) clue your readers in the first time.

Follow a style guide

Newspapers and magazines tend to follow style guidelines that have been established by organizations such as Associated Press or the University of Chicago Press. Microsoft has its own style manual. The goal of using a style guide is to ensure consistent terminology in your documentation. After all, one person's "drop down box" is another person's "drop-down list menu." One may be familiar to everyone in your organization but may be ambiguous to those outside your company. (Consider that the next time you work with an outside vendor or a contractor.)

Screen shots

Screen shots are a great way to ensure that readers can actually see what you're trying to show them. But it may be something that's better left for any training documentation you may write. Why? Let's say you have 500 documents on a particular application. Of those, 250 have screen shots. When the application is updated, the screen featured in the documentation is no longer the same as what users will see. A compromise might be to use screen shots sparingly and keep close records of their use so that you can easily identify and update them if the application or system on which they are based changes.

Let users know who wrote the document

Another way to ensure your users know your documentation is from a reliable source is to place the name of the department somewhere on the document. For example, PowerPoint presentations can use a cover sheet that includes your department's name. If you're using Microsoft Word, you can place a logo in the header or footer of a page so that users will know it's from "the documentation department." Besides letting users know who created the document, it also tells them who to contact when the document needs to be changed or updated.

Use consistent formatting

Remember our analogy of The New York Times and The Wall Street Journal? Besides adhering to graphical treatment, both newspapers use consistent fonts. Headlines are usually in a certain size range. Photos captions have some sort of attribution. The formatting you find on the first page is the same, or in the same family, as what you'll find on the last. Your documentation should be the same.

If you're just beginning to formalize your documentation, review examples of what you consider good documentation. Decide, for example, how bulleted lists should be punctuated or how long a paragraph should be before another begins. Decide how to use bold or underlining and when they are appropriate. Often, you can select documentation applications that have much of the formatting established. Or if you're using Microsoft Word, for example, you can design your own templates to ensure formatting is consistent.

When you're gathered your formatting guidelines, place them in a database and remind your documentation writers to adhere to the formatting.

0 comment(s)