docs

Documentation

Write clear, warm, well-structured documentation that helps readers accomplish their goals.

Workflow

1. Determine what needs documenting

If the user has explicitly stated what they want documented, proceed to step 2.

If not, ask:

• What are you documenting?
• What type of document is this? (see routing table below)

2. Determine the audience

If the audience is obvious from context (for example, a README in an open source library targets developers), proceed.

If not obvious, ask the user explicitly. Never assume the audience. The tone, depth, and structure all depend on who is reading.

3. Route to the appropriate guidance

Consult the relevant guide based on doc type. Every document falls into one of two categories.

User-facing documentation — apply the Diátaxis framework:

Doc type	Guide	Diátaxis category
README	readme.md	Hybrid (orientation + quickstart)
Quickstart / Getting started	quickstart.md	Tutorial
How-to guide	how-to-guide.md	How-to
API reference	api-reference.md	Reference

Decision and design documents — purpose-specific templates:

Doc type	Guide
ADR (Architecture Decision Record)	adr.md
RFC / Design doc	rfc-design-doc.md
Migration guide	migration-guide.md
Runbook	runbook.md

For all doc types, also consult:

• tone-and-voice.md — writing style and tone
• code-examples.md — standards for code in documentation

4. Explore the codebase

If it's clear what's being documented: explore the codebase first. Read relevant source files, tests, and existing docs. Then propose a document structure to the user for approval before writing.

If it's not clear: ask the user first (step 1), then explore.

5. Determine document location

Default: docs/ directory in the repo root.

Negotiate with the user if the default doesn't fit. Ask where they want the document placed.

Flag delivery gaps: if the document is clearly meant for end users (help articles, product guides, onboarding docs) and lives only in a git repo, raise this with the user: the target audience probably won't find it there. Don't scope creep into building a docs site or CI pipeline — just inform so the user can make a conscious choice.

6. Write the document

Apply guidance from the relevant doc type guide and cross-cutting concerns:

• Follow tone-and-voice.md for style
• Follow code-examples.md for any code snippets
• Follow the Diátaxis category rules for user-facing docs (don't mix types)
• Follow the purpose-specific template for decision/design docs
• Use mermaid diagrams for visual explanations — never ASCII art
• Use progressive disclosure — show the simple path first, reveal complexity on demand
• Front-load value — readers should get useful information in the first paragraph
• Substantiate claims — link to sources, reference specific files/functions

7. Lint and verify

Before presenting the document to the user, run the bundled lint script:

bash ${CLAUDE_PLUGIN_ROOT}/skills/docs/scripts/lint-docs.sh <file-or-directory>

This runs markdownlint and Vale (if installed). See linting.md for configuration details.

Additionally:

1. Verify all code examples — execute them to confirm they work in the repo's language
2. Check that all internal links resolve

Rules

• Ask, don't assume the audience when it's ambiguous
• Never mix Diátaxis types in user-facing docs — know which of the four you're writing
• Use mermaid diagrams over ASCII art for all visual explanations
• Code examples must be verified — run them to confirm they work
• Stay in the repo's language for code examples — no multi-language tabs
• Progressive disclosure — simple path first, advanced details on demand
• Substantiate claims — link to sources, don't hand-wave
• Don't scope creep into building doc delivery infrastructure — but flag when it's needed
• Lint before delivering — every document passes markdownlint and Vale