- Explanation order ←
- Backwards API docs
- Annotation styles
- API docs annotations
- Annotations in HTML
- JSON API responses in HTML
- Generated API examples
This series of articles follows an earlier series on API documentation mistakes.
Technical writing, like other specialist skills, uses some straightforward and learnable techniques that only become obvious after you’ve heard (or read) about them. This article explains one such technique, that you can use in writing as well as other forms of explanation, such as giving presentations.
Once you know how to do this right, you will see it done wrong all the time. Sorry Not Sorry.
If you really hate your readers, you’ll have started with a history of product management. Conference presentations suffer from the Historical Context Trap even more than writing, where it has a worse impact, because the audience can’t click a button to escape. They might have comfortable seats to sleep in, though.
When you start with an abstract story about product management prioritisation that sounds like all of the others, you fail to answer the reader’s first question: so what, and why do I care? You can solve this by pinpointing the reader’s problem with their current prioritisation approach, and why they need the new framework your explanation will introduce.
Once you have established that the product person reading your article will benefit from learning about yet another prioritisation framework, you can give them an example of it in action that will make them want to learn more. Then, can you teach them to understand and use it.
In general, start by identifying with the reader’s problem so you can use that shared context to teach them something new. Use the following order for your explanation.
- Concrete problem - start with a problem the reader will recognise.
- Specific solution - solve a concrete problem the reader cares about
- General solution - build on the reader’s new understanding
- Concepts - explain the general solution, so the reader can apply it to concrete problems
This sometimes means exactly reversing the existing paragraph order.
Concepts and why it works
I blame school education and academic style for the wrong-ordering problem. School curricula train us not to question or justify the relevance of the problems they set, perhaps due to their original purpose as busywork to train a new generation of industrial revolution factory workers in punctuality and obedience. Academia’s excuse, meanwhile, remains a mystery.
Most content in technical documentation appears backwards: definitions and high-level concepts first, and concrete examples last. Readers learn concepts more easily from examples, so they should appear first.
Writing docs like writing code explains that good technical writing minimises forward references, explaining concepts as they arise. Programmers in particular get this wrong, perhaps because of programming languages that force definitions-first ordering.
And if you must, discuss any historical context at the end. For better or for worse, no-one cares.