My company prizes four critical areas that matter most to businesses and developers alike: security, durability, availability, and performance. These are ordered: leaked data is the worst problem, followed by lost data, then inaccessible data, and finally slow data. We abbreviate these “SDAP” for short.
I’ve often reflected on how good documentation fulfills all of these in its own special way. These principles can be abbreviated “FACT”:
1. Factual: Is it literally accurate? (“security”)
The worst problem in documentation is for its literal meaning to be false. In this case 100% of users will do the wrong thing with your tool.
This is like a security bug because something has “tainted” your data.
2. Aligned: Does the user form the right mental model? (“durability”)
So you’ve vetted your documentation, and you know it’s accurate. But what if users misunderstand it?
Communication is a two-way street! If I tell someone, “turn left at the fountain”, and that person misunderstands what a “fountain” is, the result is the same as if I had misinformed them.
This resembles a durability bug in that concepts that “start off” as correct—i.e., as you, the author, wrote them—transmit incorrectly.
3. Coherent: Can users understand it at all? (“availability”)
If a user just can’t make sense of what you’ve written, they’re blocked and can’t proceed. They might compensate by choosing another tool!
This, of course, trivially resembles service outages.
4. Terse: Can users read it quickly? (“performance”)
Ever had to trawling through blocks of prose just to find a simple fact? Yuck! Documentation should instead be simpler, clear, and concise so that the user can learn what they need quickly then get back to building things.
Also, as in software, patterns that “optimize” one use case (i.e., a group of users) won’t necessary help others.
Top comments (0)