Docs

Decision and design documents — purpose-specific templates:

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