# Documentation

> Write and maintain documentation. Use when creating READMEs, API docs, user guides, architecture diagrams, or any technical documentation.

- Skill: `hallucinaut/documentation` (Agent Skill)
- Install (CLI): `npx skillmds@latest add hallucinaut/documentation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hallucinaut/documentation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: hallucinaut (https://skillmd.com/u/hallucinaut)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hallucinaut/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