Writing Prose

Documentation exists to transfer understanding. Every word that does not transfer understanding is a word that costs the reader without paying them. Apply these principles to assess documentation quality and identify where clarity, readability, or structure needs improvement.

Core Principles

Plain Language First

Write for the reader's comprehension, not the author's expertise.

• Use familiar words. "Use" not "utilize". "Start" not "initiate". "Show"

not "demonstrate". When a shorter, common word exists, choose it.

• One idea per sentence. Long sentences with multiple clauses force readers

to hold context while parsing structure. Split them.

• Define terms at first use. Every acronym, domain term, or jargon word

should be defined or linked when it first appears. Never assume the reader knows what you know.

• Avoid nominalizations. "Make a decision" → "decide". "Provide an

explanation" → "explain". Nominalizations hide the actor and the action.

Active Voice

Active voice connects the actor directly to the action. Passive voice hides who is responsible and makes sentences longer.

When passive is acceptable: When the actor is unknown, irrelevant, or deliberately omitted (e.g., "The request was rejected" when the actor is the system and that is obvious from context).

Concrete Over Abstract

Abstract statements make readers do extra work to ground them in reality.

• Name the thing. "The component" → "the UserProfile component". "The

method" → "authenticate()". "The file" → "config/database.yml".

• Show, don't just tell. Follow every rule or principle with a concrete

example. "Avoid side effects" without an example is half an explanation.

• Use examples for every non-obvious claim. If a developer reading the

docs for the first time might ask "what does that look like?", answer it immediately with an example.

Structure for Scannability

Readers rarely read documentation linearly. They scan for the section they need, then read that section carefully.

• Lead with the most important information. Inverted pyramid: conclusion

first, supporting detail after. Put the "what" before the "how" before the "why" (unless the "why" motivates the "what").

• Use headers to signal topic changes. Every major topic shift warrants a

header. Headers should be noun phrases or imperative verbs, not questions (questions force readers to parse them twice).

• Use lists for parallel items. Three or more parallel items belong in a

list, not a comma-separated sentence. Lists are faster to scan than prose for enumeration.

• Use tables for comparisons. When comparing two or more things across

the same attributes, a table conveys the comparison instantly. Prose comparisons require mental tabulation.

• Use code blocks for anything technical. Commands, file paths, code

snippets, environment variable names — all of these belong in code blocks, not inline prose. This signals "copy this exactly" and enables syntax highlighting.

Assessing Documentation Quality

When reviewing documentation, evaluate each piece against these dimensions:

Accuracy

Is the documentation true? Stale documentation is worse than missing documentation because it actively misleads.

• Check against current code. Do the examples still run? Do the APIs

described still exist? Do the command flags shown still work?

• Check against current behavior. Does the documented behavior match what

the system actually does?

• Flag version drift. If documentation references a version that is no

longer current, flag it even if the behavior has not changed — the version reference creates unnecessary doubt.

Completeness

Does the documentation cover everything the reader needs to succeed?

• Happy path only? Most documentation covers the success case. Assess

whether failure cases, edge cases, and common mistakes are also covered.

• Prerequisites stated? If the reader must have X installed or configured

before following the documentation, are those prerequisites stated upfront?

• Missing context? Does the reader need to understand adjacent concepts

not explained here? Are those concepts linked or explained?

Readability

Can a typical reader understand this in one pass?

• Grade level. Technical documentation should target a reading level that

does not require re-reading for comprehension. Long sentences, rare words, and deep nesting all increase cognitive load.

• Consistent terminology. If the same concept is called "user", "account",

and "principal" in different parts of the documentation, readers will not know if these are synonyms. Pick one term and use it consistently.

• Scannable structure. Can a reader locate the answer to a specific

question in under 30 seconds? If not, the structure needs improvement.

Common Documentation Smells

These patterns reliably indicate documentation that needs improvement:

Applying This to Reviews

When the technical-writer agent identifies documentation gaps or assesses documentation quality, apply these principles:

1. Classify by impact. A readability issue in a tutorial affects all

readers. An accuracy issue in a reference doc affects anyone who uses that feature. Weight your recommendations accordingly.

1. Be specific about the failure mode. "This is hard to read" is not

actionable. "This paragraph uses passive voice in every sentence, which obscures who performs each action" is actionable.

1. Suggest the direction, not the rewrite. The reviewer's job is to

identify and classify gaps, not to rewrite the documentation. Point to the principle being violated and what would satisfy it — leave the rewrite to the author.

1. Acknowledge what works. Documentation that is accurate, complete, and

readable should be noted as such. Reviewers who only identify problems provide incomplete signal.