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:

   bash

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

2. •

   Run code block syntax validation:

   bash

   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