The Documentation Prerequisite Problem
Published: 2021-05-24 • Last updated: 2021-05-29
I work with documentation often. Reading it, writing it, maintaining it. You get the idea. A reoccurring problem I encounter is this: What should I assume the reader knows? And, given the answer to this, how can I write in a way so that the reader spends as little time as possible, to learn as much as possible?
If I write too basically, that pleases the novice reader, but frustrates the advanced reader. If I write too niche, that frustrates the novice reader, but pleases the advanced reader. Alas, what to do?
I usually compromise by writing the doc that I would want to read. I then take my team into account, and tweak it based on their levels.
- Say what you need in as few words as possible. Clear and concise is key. Fluff makes the eyes glaze over
- Use plain words. If you need the technical word, then obviously use it. But no one likes to read 50-dollar-word-soup
- Make your tone strong. This lessens ambiguity. And it’s more pleasing to read
- If you find yourself explaining a topic multiple times, extract that prose into a new doc, then link it accordingly
- Avoid acronyms. Or use them, but give their meaning
Believe it or not, there’s actually US Government guidance on how to write in plain language. It’s useful stuff and I recommend it.
Good luck out there.