Author Developer Documentation

Author Developer Documentation

Purpose

Create high-quality developer documentation that is accurate, discoverable, and actionable, using progressive disclosure and verifiable guidance.

When to use

Use this skill when:

• You implemented a new feature and need docs
• You changed an API contract and must update references
• A workflow is complex and needs explanation and examples
• Onboarding friction indicates missing or outdated docs

Inputs

• The code or feature to document
• Intended audience (new contributor, on-call engineer, API consumer)
• Required level of detail (overview vs deep reference)
• Portability constraints (avoid repo-specific paths/scripts unless explicitly allowed)

Outputs

• A documentation plan:
  • what files to create/update
  • what information belongs where
• Documentation content:
  • overview and purpose
  • step-by-step instructions
  • verification steps
  • troubleshooting notes
• Examples/templates placed in adjacent examples/ and templates/ folders where applicable

Documentation principles

• Start with the conclusion: what the reader can do after reading.
• One paragraph SHOULD have one intent.
• Use MUST/SHOULD/MAY to express requirements clearly.
• Prefer progressive disclosure:
  • keep top-level docs short
  • move deep details to references, examples, and templates
• Keep guidance verifiable: include commands/checks and expected outcomes.

Steps

1. Gather context:
   • read existing docs
   • inspect relevant code paths
   • identify assumptions and environment constraints
2. Define the doc structure:
   • overview
   • when to use
   • inputs/outputs
   • workflow steps
   • verification
   • troubleshooting
3. Write the “happy path” first:
   • minimal steps to succeed
   • explicit prerequisites
4. Add progressive disclosure:
   • move long code blocks into examples/
   • move reusable scaffolds into templates/
   • put deep rationale into reference.md (optional)
5. QA (required):
   • verify examples are coherent and do not include secrets
   • ensure requirements are explicit
   • ensure the doc matches current implementation

Verification

• Documentation structure follows the defined outline
• Requirements are explicit (MUST/SHOULD/MAY) where relevant
• Examples are coherent and do not include secrets
• Verification steps are actionable (commands/checks + expected results)
• Documentation matches current implementation
• Progressive disclosure is applied (top-level docs are short)

Boundaries

• MUST NOT include secrets, credentials, or internal-only URLs in documentation
• MUST NOT publish unverifiable instructions (“just run it”) without commands and expected outcomes
• MUST NOT copy large code blocks verbatim into top-level docs; move them into examples/
• SHOULD NOT mix multiple topics in a single document section
• SHOULD keep top-level docs within a reasonable length by using progressive disclosure

Included assets

• Templates: ./templates/doc-outline.md includes a documentation outline.
• Examples: ./examples/ includes a sample progressive doc structure.