Code Documentation

Code Documentation Skill

Create clear, concise, and informative, accurate, idiomatic, and useful documentation — not boilerplate. Every piece of documentation you write should help the next developer understand why, not just what.

Step 1: Detect Context and Scope

Before writing anything, scan the existing code and any existing docs to detect:

1. Style already in use — check for: Google style, NumPy/Sphinx style, reStructuredText, or no style
2. Existing doc coverage — are some things documented? Mimic that style exactly.
3. Project type — library/package, application, CLI tool, API server, etc.
4. Audience — internal tool vs public-facing API (affects verbosity)

If no style exists, default to Google style docstrings.

Always announce your detected style to the user before writing, e.g.:

"I can see you're using Google-style docstrings — I'll match that throughout."

Step 2: Determine Scope

Ask or infer which documentation type(s) are needed. See the full guidance in:

• references/inline-docs.md — docstrings and inline comments
• references/readme-and-api.md — README files and API reference docs
• references/architecture.md — high-level architecture and design docs

For multi-type requests (e.g. "document this whole project"), tackle in this order:

1. Inline docs first (they inform everything else)
2. API reference
3. README
4. Architecture doc

Step 3: Write Documentation

Universal rules (apply to all doc types)

• Document intent, not mechanics. If the code says i += 1, don't write # increment i.
• Keep it current. If you see a comment that contradicts the code, fix the comment.
• Don't over-document. Private helpers and obvious one-liners rarely need docs. Focus effort on: public APIs, complex logic, non-obvious side effects, error conditions.
• Be consistent. Use the same style, tense, and voice throughout a file.
• Examples > prose for complex APIs. A 3-line usage example beats a paragraph of explanation.

What to always include in function/method docs

Only include sections that apply — don't add empty Raises: if nothing is raised.

Step 4: Output Format

• Inline docs: Output the full modified file (or clearly-delimited diff if file is large). Never output just the docstring in isolation — always show it in context.
• README: Output as Markdown. See references/readme-and-api.md for structure.
• API reference: Output as Markdown table or structured Markdown. See references/readme-and-api.md.
• Architecture doc: Output as Markdown with diagrams (Mermaid) where helpful. See references/architecture.md.

Step 5: Offer Follow-ups

After completing documentation, offer at least one relevant next step, e.g.:

• "Want me to generate an API reference from these docstrings?"
• "Should I write a README for this module next?"
• "Want me to add usage examples to the more complex functions?"