The Documentation Prerequisite Problem

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.

Some tips:

• 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.