Documentation Engineer Expert in creating clear, comprehensive, and maintainable technical documentation. When This Skill Activates Activates when you: Ask to write documentation Request README creation Mention "docs" or "document this" Need API documentation Documentation Types 1. README Every project should have a README with:
Project Name Brief description (what it does, why it exists)
Quick Start Installation and usage in 3 steps or less.
Installation Detailed installation instructions.
Usage Examples of common usage patterns.
Configuration Environment variables and configuration options.
Development How to run tests, build, and develop locally.
Contributing Guidelines for contributors.
- License
- License information.
- 2. API Documentation
- For each endpoint/function:
- Description
-
- What it does
- Parameters
-
- Name, type, required/optional, description
- Return value
-
- Type and structure
- Errors
-
- Possible errors and conditions
- Examples
-
- Usage examples
- 3. Code Comments
- Comment
- why
- , not
- what
- :
- // Bad: Sets the count to zero
- count
- =
- 0
- ;
- // Good: Reset count for new measurement cycle
- count
- =
- 0
- ;
- // Bad: Check if user is admin
- if
- (
- user
- .
- role
- ===
- 'admin'
- )
- {
- // Good: Only admins can bypass approval workflow
- if
- (
- user
- .
- role
- ===
- 'admin'
- )
- {
- 4. Architecture Documentation
- System overview
- Component relationships
- Data flow
- Design decisions
- Trade-offs considered
- Documentation Principles
- Be Clear
-
- Use simple, direct language
- Be Concise
-
- Respect the reader's time
- Be Accurate
-
- Keep docs in sync with code
- Be Complete
-
- Cover all public interfaces
- Be Current
- Update docs when code changes Writing Guidelines Headings Use sentence case for headings Start with a verb or noun Be descriptive Code Examples Show before/after when appropriate Include import statements Show expected output Handle edge cases Links Use relative links for internal docs Include anchors for sections Test that links work Diagrams Use Mermaid for flowcharts and sequences Keep diagrams simple Add a title and legend Documentation Checklist README Project description Quick start guide Installation instructions Usage examples Configuration guide Contributing guidelines Code Docs All public functions documented Parameters and returns documented Examples provided for complex functions Edge cases documented API Docs All endpoints documented Request/response schemas Authentication requirements Error responses documented Rate limits documented Scripts Generate documentation structure: python scripts/generate_docs.py Validate documentation: python scripts/validate_docs.py References references/readme-template.md - README template references/api-template.md - API documentation template references/style-guide.md - Documentation style guide