How to write great documentation

I recently took part in a conversation about how technical writers and developers can write better documentation. There were a lot of great tips about writing style and audience. I wanted to share these 4 highlights from that conversation:

1. Write for your audience

When writing any kind of document, whether it's a "Readme" file for an IT project or a "quick start" guide for the end user, consider who will read the documentation. This is your audience. If your documentation is a "Readme" with build instructions for another developer, then you can likely assume the person reading the document has a basic understanding of certain terms. The reader will read the "Readme" file to understand how to build the software and perform certain basic tests. So focus on that. The "Readme" should describe what the reader needs to do.

But if your document is intended for end users, you might need a different set of assumptions. The reader probably doesn't need to know anything about how the software was built, only how to install it on a computer and start working with it. These readers need more visuals and diagrams that walk them through the steps of installing the application, launching it, and using the software. This "quick start" guide needs to provide the basics of how to run and use the software.

And the old advice is still true: When in doubt about how to write a "how-to" document, write it as though you were explaining the process to a friend.

2. It's about quality, not quantity

Sometimes, technical writers fall into the trap of thinking more is better. But the opposite is usually true: it's not about the length, but about the content.

When writing any kind of document, start by asking why the user will read the document, and focus on writing a quality document that provides that. For example, a user guide for a remote control needs to explain the buttons and what they do. Start with a diagram that identifies the buttons, with arrows or other pointers to show the most commonly used buttons. Provide a table that lists the functions of each button. Conclude with technical specifications if needed, or a URL to a product website for more information and support.

This user guide might only need one page for the diagram and two pages for the table, and a final page for the technical specifications. That's four pages, and that suits the needs of the reader.

3. Write as you go

When we're working on a project, we might get swept up with the project details, timelines, and deadlines. It might be tempting to "save" the documentation until the end of the project, perhaps under the assumption that writing the documentation will be easier when the project is complete, and you know how everything fits together.

But waiting until the end of the project can make the documentation phase more daunting. Writing the documentation from scratch for an entire project takes a long time. If you wait too long to start writing the documentation, it may be too late.

Instead, write the documentation as you go. Don't worry too much about making this documentation perfect; consider it "draft" material that you will edit later. When the project is complete, it will be easier to assemble the drafts into a cohesive final product.

4. Use images and diagrams

The old adage of "a picture is worth a thousand words" remains true today. For project documentation, a diagram can explain most processes more easily than describing it in prose. For end user documentation such as a "how-to," a series of screenshots will more easily guide your user through the steps to install or use the software.

If your process requires more detail, interleave written text with diagrams or screenshots. For example, if you needed to document the steps to send an encrypted email, you might describe the first step in a few brief sentences, then include a screenshot showing the buttons to click or the menu to navigate. Do the same for each step in the process: describe it in a few sentences, then show it in a screenshot or diagram. Most people are visual learners; this visual walkthrough is often the most efficient way to describe a series of steps.