There are two approaches to documenting technical instructions. The first is to tell users everything that can be done with the product in as much detail as possible. It’s usually a field-by-field, control-by-control account. At Taylfin, we refer to this as the mini-spec approach, because the manual starts to resemble a user interface specification. With each release, the manual grows to take account of all the changes and additions to the product in exquisite detail, without much regard for how this new information fits into the user’s experience of the product.
The second approach is to tell users what they’re most likely to do in only as much detail as required. We call this selective revelation: You tell users only what they need to know when they need to know it. This is actually harder than the mini-spec approach because it requires a bit of up-front work in figuring out who the audience is, what they need to know and how they’re likely to approach things. But it’s better in the long run, because it results in a document that is actually useful to users. It’s also less effort to maintain.
One reason why technical people shy away from the selective revelation approach is that they feel like the technology is being dumbed down. But selective revelation isn’t about dumbing it down, it’s about gradually laying down a foundation for users, then building on that foundation. It’s about teaching, which is what good technical documentation should do.
Think about it like this. When teaching kids about colours, we initially get them to recognise broad classes of colour such as red, blue, green, yellow, purple, orange, pink and brown. We leave until later all the subtle in-betweens like mauve, chartreuse, magenta, teal, vermillion and so on.
This is selective revelation.
But the mini-spec is not evil, there are times when it is useful. The mini-spec approach is about informing rather than teaching. It’s effectively giving a user all the information they need and trusting them to make the most of that information in their use of your product. It’s good for advanced audiences who are likely to have a good grasp of your product’s domain before they ever crack the seal. They know exactly what your product does, the only mystery is how it does it. This is where the mini-spec approach comes in handy.
The mini-spec approach requires a commitment to minimalism. If you’re taking this approach:
- Resist the urge to add more. All your audience is looking for is information. What does this button do? What is this field for? What are its dependencies? Nice introductions and evocative descriptions are simply going to get in the way of your audience finding the information they need.
- Use pictures sparingly. Pictures should only be added when they contribute to informing the reader, teaching them how to get the most out of the product. Pictures should never be added as filler.
- Stick to describing how to use the product rather than trying to sell it. Okay, yes, this is a variation on resisting the urge to add more. But it’s important. Sales information does not belong in the mini-spec. The product has been bought and paid for and the reader is trying to get the most out of it. Salesy stuff is just a distraction.
The disadvantage of the mini-spec is that it is a dry read. But the reader isn’t looking for entertainment, just information. If you choose carefully when to use the mini-spec approach, know your audience and give them what they want (and nothing more), you will make them happy.