4 More Low-Tech Documentation Tips

When I shared low-tech documentation tips with you last month, I left out the to be continued part. "Tips and tricks" can be overwhelming. There's so much information out there that it can be hard to know which ones to apply or where to even start. It's easy to become paralyzed and do nothing. (I may or may not be speaking from experience.) 

So here are a few more specific actions you can take to improve the accuracy and quality of anything you write. Try one or all and see what might work for you.

1. Start a Style Sheet 

(Stick with me here.) A style guide is a comprehensive set of documentation rules. It can cover hyphenation rules, when to spell out numbers (vs. using numerals), and many other usage guidelines. Your organization might maintain their own in-house style guide or it may adopt one that's already out there (e.g., Chicago Manual of Style). A style guide helps ensure consistency in usage as well as brand and voice, depending on the organization. Think of it as a set of guard rails.

(Still there?) A style sheet is generally a shorter version of a style guide and serves as a running list of document decisions not already answered in your governing style guide or dictionary. It doesn't override style guide rules but can go a bit beyond them if there are requirements specific to a project. (I generally follow a commercial style guide and then create a style sheet for each project I work on.)

• Does your current project include proprietary terms that you can never remember how to spell? List them in the style sheet.
• Do you want to format images with a 2pt border in navy? List that in the style sheet.
• Are you formatting headings as sentence style or all caps? You guessed it: style sheet.

A style sheet is also a living document that can be updated as the project evolves and decisions are made--from formatting to terminology (e.g., "client" vs. "user"). And it can be posted easily to a shared drive for use among a team to ensure consistent documentation throughout the project. 

This isn't only a tool for control freaks who must have everything documented and organized. Project to project, a style sheet does the remembering for us. I may decide to format button names in all caps on Friday and then on Monday (after a fun weekend) I find myself asking, How are we formatting buttons again? The style sheet documents the decisions I already made so I don't have to remember them--because I won't remember them. This aspect is especially useful when working on multiple projects with different specifications.

A style sheet doesn't have to be fancy, unless you want it to be. A simple MS-Word document with a list of terms and brief formatting descriptions works for me. And I make it easy by stealing from myself: I open a recent style sheet and work the Save As magic so I don't have to create the style sheet from scratch each time. 

Here are a few examples (not mine): 

• Bay Area Editors' Form
• Tweed Editing
• Institute of Education Press

Mine look more like the first one, but you can be as detailed as you like.

The best part about a style sheet? When I win the lottery, my replacement will easily slide into the project with a clear understanding of the documentation up to that point.

2. Consider Your Audience 

Besides having to learn the content you're writing about, you also need to understand who you're writing for. Without considering your audience, you can end up with documentation that isn't understood and, therefore, not usable by its intended readers. 

What does your audience already know about the topic? 
What do they want to know? 
What do they need to know? 

What was helpful to you when you were learning about this topic?

Answers to these questions help you decide how much background information you need to provide before getting into the new stuff. For example, if the audience currently uses the product, they only need to learn what has changed. If they have never used your product--or its platform--you may need to include more direction to bring the audience up to speed.

How will they get your documentation? 

Is this for a printed manual or are you publishing .pdfs to an online shared site? Or both?

Are you creating chunks of information in online help that's integrated into your product? 

Answers to these questions help you determine how to present the information, including formatting for readability. They also lead to more questions (sorry), such as should/can you include internal reference links and will a table of contents or search feature be useful? You can get deep in the weeds here, but the point is to include your readers and their needs when you're writing; you're writing for them after all. 

I worked on a project years ago for Avon. They were rolling out laptops to regional managers across the country. I was responsible for the training manual and video script to help them learn MS-Windows and perform basic tasks using MS-Word, MS-PowerPoint, and MS-Excel. While observing from the back of the room during a pilot training session, I watched a lady pick up her mouse, look at the bottom of it, and then swipe it back and forth across her keyboard. 

The lesson? We can't always know what our audience doesn't know. But asking the right questions and approaching projects as a new user can make a big difference. 

3. Remember: Names Mean Things

Here's a simple one that I see often: someone wrote a useful document but no one can find it on the departmental SharePoint site because the file name doesn't match the document name--or what the document is really about. For example, the "Laboratory Technician Guidelines" document is named "SampleTesting.doc." How would anyone know to look there?

Name your files the same as (or close to) the document title. So in six months when the document needs to be revised or accessed by auditors or new hires, it can be found.

(It's also a good idea to include file naming conventions in your style sheet.)

4. Format for Readability

Format any user interface elements (e.g., buttons, menu names, field names, etc.) to create context for increased reader comprehension. For example, you decided that button names will be all caps and bold. You'll apply that formatting for all button names when they're mentioned in your documentation. This builds the readers' expectations so they will know you're referring to a button when they see that formatting. 

You'll also document those formatting choices in your style sheet. If you're uncomfortable making these types of decisions, take a look at the Microsoft Style Guide. You may want to adopt it if you write a lot of computer-related documentation.

Just don't overdo it. Take a look at this image to the right. On this project, the writers were tasked to follow a corporate template and style guide that included multiple icons that were confusing to users. The template also required all steps to be formatted in bold. This meant they had to be creative in calling out interface elements like buttons and field names (because you can't make something bold when it already is). The result is a busy document that's hard to read. Do you agree?

That's all folks. More low-tech wins in the name of accurate, understandable, and usable documents.

Let me know if you try any of these tips and how they worked for you. And, please, ask me if something isn't clear; I welcome that feedback as well.

Thanks for reading. See you soon.