Writing User Guides

Writing User Guides

A user guide provides information that a user would need in day-to-day use of the product. User guides may have a little bit more of a “narrative” voice compared to reference guides and READMEs.

Guidelines

Users come first

It’s important that the user guide is written with the audience in mind.

• Who are your users? Are they developers, sysadmins, or DBAs? What skills and knowledge level do they already have related to the product?
• What do your users do on a daily basis?
• How does the product fit into their work?

Make it scannable and easy to navigate

The reader may not be going through the user guide in a linear way, especially if they are looking for information about a specific task. Include a table of contents that also allows the reader to jump to a particular section.

User guides are typically less terse than reference guide, but you should still avoid walls of text.

It’s not an encyclopedia

The user guide does not have to contain every single piece of information about everything to do with your product. Remember that this document is primarily meant to support day-to-day use. For example, some developer-specific content can go in a README instead of the user guide.

Don’t skimp on the details

For the information that does make it to the user guide, be appropriately thorough. If completing a task requires a series of actions, err on the side of being explicit (e.g. number each step in the right order, and include no more than two actions per step).

Template

We have a user guide template available that you can check out. Feel free to reference or download and use the files as you see fit for your project.