Documentation FundamentalsLesson 1.5
Writing style guide for developer documentation
active vs passive voice, second-person writing, plain language principles, sentence length, avoiding jargon, consistent terminology, imperative mood for instructions
Style Guide for Developer Docs
Style consistency makes documentation predictable. Readers stop noticing the writing and focus on the content. That's the goal.
Core Style Rules
- Use second person. Write "You can configure" not "The user can configure" or "One can configure."
- Use active voice. "The function returns a string" not "A string is returned by the function."
- Use imperative mood for steps. "Run the command" not "You should run the command" or "The developer runs the command."
- Keep sentences under 25 words. Long sentences hide meaning. If a sentence needs a semicolon, split it.
Terminology Consistency
Pick one word per concept and use it everywhere. Never alternate between "endpoint," "route," and "URL" in the same doc. Create a glossary for your project's domain terms and link to it.
What to Avoid
- "Simply" and "just" — condescending to anyone who finds it hard
- "Obviously" and "clearly" — never obvious to a reader who's stuck
- Passive constructions that hide who does what
- Acronyms without first-use expansion
Test Your Writing
Read your doc aloud. Wherever you pause or trip over a sentence, rewrite it. If it sounds awkward spoken, it reads awkward too.