Skip to main content

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.

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.