Documentation

Documentation Skill

Create clear, comprehensive, and maintainable documentation.

When to Use

Use this skill when the user wants to:

• Write or update README files
• Create API documentation
• Write user guides and tutorials
• Document architecture and design
• Maintain changelog and release notes
• Create inline documentation
• Generate documentation from code

Documentation Types

Project Documentation

• README: Project overview, installation, usage
• CHANGELOG: Version history and changes
• CONTRIBUTING: Guidelines for contributors
• LICENSE: Legal information
• WELCOME: Onboarding information

Code Documentation

• Inline comments: Explain complex logic
• Function signatures: Document parameters and return values
• Docstrings: Descriptive text for functions, classes, modules
• JSDoc/TypeDoc: Documentation for JavaScript/TypeScript

API Documentation

• OpenAPI/Swagger: API specification
• API reference: Endpoints, parameters, responses
• Code examples: Usage examples
• Error codes: Explanation of errors

User Documentation

• Tutorials: Step-by-step guides
• User guides: Feature explanations
• FAQ: Common questions and answers
• Troubleshooting: Problem-solving guides

Documentation Principles

Clarity First

• Write for your audience
• Use simple, clear language
• Avoid jargon unless necessary
• Explain acronyms

Completeness

• Cover all important topics
• Include examples
• Document edge cases
• Keep up to date

Usability

• Organized with clear structure
• Easy to find information
• Concise but thorough
• Visual aids where helpful

Maintainability

• Version with code
• Use documentation generators
• Keep documentation in source control
• Review documentation in PRs

Documentation Tools

Markdown

• Standard documentation format
• Supported by most tools
• Easy to learn

Documentation Generators

• JSDoc: JavaScript/TypeScript
• Sphinx: Python
• Javadoc: Java
• Doxygen: Multiple languages
• TypeDoc: TypeScript

API Documentation

• OpenAPI/Swagger: API spec
• Swagger UI: Interactive docs
• API Blueprint: API design
• GraphQL: Schema documentation

Diagram Tools

• Mermaid: Text-based diagrams
• PlantUML: Diagram generation
• Draw.io: Visual diagrams
• Graphviz: Graph visualization

Best Practices

README Guidelines

• Clear title and description
• Installation instructions
• Quick start example
• Usage examples
• Project structure
• Contributing info
• License

Code Comments

• Document complex logic
• Explain why, not what
• Keep comments up to date
• Avoid commenting obvious code

API Documentation

• Document all endpoints
• Include request/response examples
• Explain status codes
• Document authentication
• Use consistent naming

User Guides

• Use numbered steps
• Include code examples
• Add screenshots
• Organize with headings
• Use tables for data

Deliverables

• Updated documentation files
• Documentation structure
• Diagrams and visuals
• Examples and tutorials
• API documentation

Quality Checklist

• Documentation is up to date
• Errors are documented
• Examples work correctly
• Structure is clear
• Tone is consistent
• Formatting is consistent
• Links are valid