documentation

Documentation

This skill governs how you write. Section 1 applies to all text you produce — code comments, chat responses, documentation. (Commit messages are governed by commit-hygiene, which owns that jurisdiction in the §5 routing table.) Section 2 applies when you are producing or editing a standalone document (README, guide, reference page, explanation, specification).

---

Section 1: Core Writing Principles

These rules are always active. They are non-negotiable.

1. Answer First

Lead with the conclusion, not the context. The reader's question should be answered in the first sentence or heading — background, caveats, and methodology come after. If someone stops reading after one paragraph, they should still have the answer.

2. Active Voice

Default to active voice. Use passive only when the actor is genuinely irrelevant or unknown. "The function returns an error" — not "An error is returned by the function."

3. Sentence Economy

One idea per sentence. Delete words that don't earn their place. If a sentence works without a word, remove that word. Prefer concrete language over abstract hedging.

4. Terminology Lock

Once you name a concept, use that name everywhere. Do not swap synonyms for variety — consistency beats prose elegance. If the codebase calls it a "store," never call it a "repository" or "database" in documentation. Terminological inconsistency is a documentation bug.

5. Scannable Structure

Readers scan before they read. Support this:

• Use meaningful headings (not "Overview" or "Introduction" — say what the section contains)
• Use bullet points for lists of 3+
• Bold key terms on first use
• Front-load important words in headings and list items

6. No Filler

Do not pad text with words that add no information.

[!CAUTION] Anti-Patterns (FORBIDDEN):

• ❌ Preamble walls: "In this section, we will discuss the various aspects of..."
• ❌ Restating the question: "You asked about X. X is an important topic. Let me explain X."
• ❌ Hedge-word padding: "It's worth noting that perhaps it might be considered..."
• ❌ Empty transitions: "Now let's move on to the next topic."
• ❌ Compliment-before-content: "Great question! That's a really interesting point."
• ❌ Metatext about your own process: "I'll analyze this step by step."

✅ Correct behavior: Start with the substance. If a paragraph's first sentence could be deleted without losing information, delete it.