Best Practices for End-User Docs (SaaS)


Moving this from Introductions.
@lori1goldman @bradamante @tripwire45

Let’s talk about best practices for end-user docs.

Here’s a question to start… I’m finishing up an audit based on new consistency/style guidelines, but since we just redesigned our KB we want our next audit to focus on structure and organization. How does everyone structure their docs (prereqs, reference details, procedures, etc)?


Hi Emily,
I quickly wrote the following response. I hope it helps.

Near the beginning of the software user guide, there is a section that describes the purpose of the document, the audience, new features, and maybe a related docs list.

The next section talks about system requirements. After that, it’s basically all procedural content.

Procedures are written something like this:

  • I give a very clear purpose statement in the first line.

  • If there are any procedures that closely (very closely) resemble the one I’m describing, I’ll mention it right after the purpose and provide the cross-reference. If two procedures sound similar, this is a way to make sure the user can find the one they need asap.

  • In the next paragraph, I might add a “note” to briefly explain what’s not covered, if that’s necessary. It’s basically a scope statement. It can be useful when you don’t want to repeat simple instructions that are easily found elsewhere.

  • Prerequisites usually come next, but sometimes they come in a whole section above this one. It’s a judgement call. I like them to be as close to step one of the procedure as possible. By the way, prereqs shouldn’t be things that the reader already knows. For example, you’re not going to make “a physical computer with a monitor attached” a prereq in a section that describes how to install software on a computer, unless maybe you’re in the virtual desktop business and it’s not obvious to your readers that the computer should have a monitor attached (i.e. the software can’t be installed on a virtual machine).

Next are the procedure’s steps, or as I prefer to call them, the instructions.

  • I often will add a line immediately after the last step in the instructions, to explain what will happen (or what they’ll see) after they’re done performing the steps. This helps the reader know whether they’ve done everything correctly.

  • If there is anything more to tell them, I might add a few bullet points directly after, under the heading “Notes”, but that’s rare. I first want to determine whether the content I want to include as notes could fit somewhere else in the document.