The Documentation Prerequisite Problem

Published: May 24, 2021
Updated: May 29, 2021

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:

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.