The Three Pillars of Technical Writing
Study Reveals Most Technical Documents Fail at Least Two of Three Basic Requirements
Understanding written text depends on three distinct components. Master these, and your documentation will actually be useful. Ignore them, and you might as well not write anything at all.
1. Legibility
Can the reader physically see and decode the characters? This is about fonts, layout, and typography—usually handled by designers and typesetters, not writers.
(We won't cover this—it's not your job. But don't use Comic Sans.)
2. Readability
Can the reader process the text smoothly? This is about sentence structure, word choice, and flow. If a text is unreadable, the reader will assume the product is equally poor quality.
Think of it as "tokenizing" your text—making it easy to parse.
3. Comprehensibility
Can the reader actually understand the meaning? This is about logical structure, building on prior knowledge, and clear explanations. This is where most technical writing fails.
Think of it as "parsing" your text—extracting meaning from tokens.
The Brutal Truth
If your technical text is unreadable, readers will assume your product is also of inferior quality. Code is a language, just as documentation is. Not writing well in documentation implies faults in coding style. Fair or not, this is how humans judge quality.
Quick Check
Which pillar of technical writing is most often neglected by programmers?