Writing Documentation

Writing Documentation

Overview

Expert technical documentation skill for creating clear, accurate, user-friendly documentation. Handles lightweight documentation tasks directly and delegates comprehensive tasks to the writing-documentation agent.

When to Use This Skill

Use writing-documentation when you need to create:

• API documentation from code (OpenAPI, endpoint references, authentication docs)
• User guides and tutorials (getting started, feature walkthroughs)
• Architecture documentation (system design, ADRs, component diagrams)
• Operational docs (runbooks, deployment guides, troubleshooting)
• Project documentation (comprehensive READMEs, CONTRIBUTING guides)

Handoff Rules

To updating-readme skill

For maintaining existing READMEs (section updates, dependency changes, minor edits), use updating-readme instead. This skill creates; updating-readme maintains.

To writing-documentation agent

Delegate to the writing-documentation agent via the Task tool when ANY of these apply:

• Output will be multiple files
• User guide will exceed 500 words
• Requires architecture documentation or ADRs
• API documentation requires analyzing more than 3 source files
• Creating documentation from scratch for an undocumented project
• Task requires deep codebase analysis

How to delegate: Use the Task tool with agent writing-documentation. Example:

Task: writing-documentation
Prompt: Create comprehensive API documentation for the authentication module including all endpoints, request/response schemas, and error codes.

Decision Matrix

Quick Reference

Process

When asked to create documentation:

1. Scope Assessment: Determine if this should be delegated to the agent (see Decision Matrix above)
2. If delegating: Use Task tool with writing-documentation agent
3. If handling here:
   • Analyze the code/system to understand what needs documenting
   • Read the appropriate workflow file:
     • API docs → Read workflows/api-docs.md
     • User guide → Read workflows/user-guide.md
     • Architecture → Read workflows/architecture.md
     • Troubleshooting → Read workflows/troubleshooting.md
   • Read the matching template:
     • API docs → Read templates/api-reference.md
     • README → Read templates/readme-comprehensive.md
     • ADR → Read templates/adr.md
     • Runbook → Read templates/runbook.md
     • User guide → Read templates/user-guide.md
   • Follow the workflow steps
   • Run validation loop
   • Deliver documentation

Core Principles

Audience Awareness

Always identify the target audience before writing:

• End Users: Simple language, task-oriented, minimal jargon
• Developers: Technical details, code examples, API specifics
• Administrators: Configuration, deployment, maintenance
• Contributors: Architecture, conventions, processes

Documentation Standards

Structure

• Clear hierarchy with consistent heading levels
• Table of contents for documents > 500 words
• Cross-references between related sections
• Progressive disclosure (basic → advanced)

Content

• Lead with the most important information
• Use active voice and direct instructions
• Include practical examples for every concept
• Provide both quick-start and comprehensive paths

Code Examples

• Validate all code examples for syntax correctness
• Include expected output where applicable
• Show error handling, not just happy path
• Use realistic, not trivial, examples

Format Guidelines

Markdown Best Practices

• Use fenced code blocks with language hints
• Tables for structured comparisons
• Consistent formatting throughout

API Documentation Standards

• HTTP method and path clearly visible
• All parameters documented (path, query, body, headers)
• Request and response examples
• Error responses with codes and messages
• Authentication requirements

Validation Loop (Required)

After generating any documentation, run validation until clean:

1. Run documentation validation:

   python .claude/skills/writing-documentation/scripts/validate_docs.py <output_file>
   

2. Run code block syntax validation:

   python .claude/skills/writing-documentation/scripts/check_code_blocks.py <output_file>
   

3. If ERRORs found in either:

   • Fix all ERROR items (placeholders, empty code blocks, syntax errors)
   • Re-run both validations

4. If WARNINGs found:

   • Address straightforward warnings (missing language hints)
   • Re-run validations

5. Repeat until both pass or only acceptable warnings remain.

6. Never deliver documentation with unresolved ERRORs.

Quality Checklist

Before delivering documentation, verify:

• Target audience is clear
• All code examples are syntactically correct
• No placeholder text remains
• Cross-references are valid
• Prerequisites are complete
• Examples are realistic and useful
• Error cases are documented
• Document is self-contained (or links to dependencies)
• Validation script passes

Integration with updating-readme

After creating a README:

• Future section updates → updating-readme skill
• Future dependency additions → updating-readme skill
• Future config changes → updating-readme skill
• Complete rewrites → back to this skill or agent

Examples

See examples/ for complete output samples:

• examples/api-example.md — User Management API reference
• examples/guide-example.md — CLI tool user guide