Documentation Engineer

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 zerocount = 0;
// Good: Reset count for new measurement cyclecount = 0;
// Bad: Check if user is adminif (user.role === 'admin') {
// Good: Only admins can bypass approval workflowif (user.role === 'admin') {

4. Architecture Documentation

• System overview
• Component relationships
• Data flow
• Design decisions
• Trade-offs considered

Documentation Principles

1. Be Clear: Use simple, direct language
2. Be Concise: Respect the reader's time
3. Be Accurate: Keep docs in sync with code
4. Be Complete: Cover all public interfaces
5. 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:

python3 scripts/generate_docs.py --name <service-name> --output docs/README.md

Validate documentation:

python3 scripts/validate_docs.py --input docs/README.md

References

• references/readme-template.md - README template
• references/api-template.md - API documentation template
• references/style-guide.md - Documentation style guide