## Documentation Framework ### Phase 1: Documentation Audit ``` Audit documentation needs for: **Project:** [Repository or project name] **Current Docs:** [Existing documentation if any] **Audience:** [Internal devs, external users, both] Assess documentation gaps: 1. **Essential Documentation** - [ ] README with quick start - [ ] Installation guide - [ ] API reference (if applicable) - [ ] Contributing guide - [ ] License file 2. **Developer Documentation** - [ ] Architecture overview - [ ] Local development setup - [ ] Testing guide - [ ] Debugging tips - [ ] Code style guide 3. **Operational Documentation** - [ ] Deployment guide - [ ] Configuration reference - [ ] Monitoring and alerting - [ ] Troubleshooting runbook - [ ] Incident response 4. **User Documentation** - [ ] Getting started tutorial - [ ] Feature documentation - [ ] FAQ - [ ] Migration guides Create prioritized documentation roadmap. ``` ### Phase 2: README Excellence ```` Generate a comprehensive README for: **Project:** [Name] **Description:** [What it does] **Stack:** [Technologies used] Structure: 1. **Header Section** - Project name with logo (if available) - Badges: build status, version, license, coverage - One-line description - Key features (3-5 bullet points) 2. **Quick Start** ```markdown ## Quick Start ```bash npm install my-package import { feature } from 'my-package'; feature.doSomething(); ```` ``` 3. **Installation** - Prerequisites (Node version, OS requirements) - Step-by-step installation - Verification steps - Common installation issues 4. **Usage Examples** - Basic example with explanation - Advanced example showcasing features - Configuration options table 5. **API Reference** (brief, link to full docs) - Main exports and their purpose - Type definitions or signatures - Link to detailed API docs 6. **Contributing** - How to report bugs - How to request features - Development setup - PR process 7. **License & Credits** - License type - Acknowledgments - Related projects Generate complete README.md with proper formatting. ``` ### Phase 3: API Documentation ```` Generate API documentation for: **API Type:** [REST, GraphQL, Library] **Source:** [OpenAPI spec, code, or descriptions] Documentation components: 1. **API Overview** - Base URL and versioning - Authentication methods - Rate limiting - Error handling conventions 2. **Endpoint Documentation** (for each endpoint) ```markdown ## Create User Creates a new user account. `POST /api/v1/users` ### Request **Headers:** | Header | Required | Description | |--------|----------|-------------| | Authorization | Yes | Bearer token | | Content-Type | Yes | application/json | **Body:** ```json { "email": "user@example.com", "name": "John Doe", "role": "member" } ```` ### Response **201 Created** ```json { "id": "usr_abc123", "email": "user@example.com", "name": "John Doe", "createdAt": "2026-01-14T12:00:00Z" } ``` **400 Bad Request** ```json { "error": { "code": "VALIDATION_ERROR", "message": "Email is required" } } ``` ``` 3. **Code Examples** - Examples in multiple languages (curl, JavaScript, Python) - Complete, runnable code - Error handling included 4. **SDK Reference** (if applicable) - Installation - Configuration - Method signatures with types - Usage examples Generate complete API documentation. ``` ### Phase 4: Architecture Documentation ```` Document system architecture for: **System:** [Name] **Components:** [List main components] **Stakeholders:** [Who needs to understand this] Architecture documentation: 1. **System Overview** - High-level architecture diagram - Component responsibilities - Technology choices and rationale - Design principles followed 2. **Component Details** For each major component: - Purpose and responsibilities - Interfaces and APIs - Data models - Dependencies - Scaling characteristics 3. **Data Flow Diagrams** - Request/response flows - Data transformation steps - Async processing flows - Error handling paths 4. **Architecture Decision Records (ADRs)** ```markdown ## Status Accepted ## Context We need a reliable database for storing user data and transactions. ## Decision We will use PostgreSQL 15 as our primary database. ## Consequences - **Pros:** ACID compliance, strong ecosystem, team familiarity - **Cons:** Requires more ops work than managed NoSQL - **Mitigations:** Use managed service (RDS/Cloud SQL) ```` 5. **Deployment Architecture** - Infrastructure diagram - Environment configurations - Networking and security - Monitoring and observability Generate architecture documentation with Mermaid diagrams. ``` ## Documentation Formatting ``` Apply consistent formatting: **Style Guide:** - Use sentence case for headers - Keep paragraphs short (3-4 sentences max) - Use bullet points for lists - Include code examples in fenced blocks - Add language hints to code blocks **Visual Elements:** - Mermaid diagrams for architecture - Tables for configuration options - Callouts for warnings/tips - Screenshots with annotations **Accessibility:** - Alt text for images - Descriptive link text - Clear heading hierarchy - Avoid jargon without explanation **Maintenance:** - Date last updated - Version compatibility notes - Links to related docs - Feedback mechanism ```` ## Best Practices 1. **Write for Your Audience**: Adjust technical depth based on readers 2. **Show, Don't Tell**: Use examples liberally 3. **Keep It Updated**: Outdated docs are worse than no docs 4. **Be Concise**: Respect readers' time 5. **Use Consistent Formatting**: Same patterns throughout 6. **Include Context**: Explain why, not just how 7. **Make It Searchable**: Use clear headings and keywords 8. **Test Your Docs**: Follow your own instructions ## Example Session **User**: "Create a README for my CLI tool that converts markdown to HTML." **Response**: > ```markdown > # md2html > > [](https://badge.fury.io/js/md2html) > [](https://opensource.org/licenses/MIT) > > A fast, lightweight CLI tool for converting Markdown files to HTML with syntax highlighting and custom themes. > > ## Features > > - 🚀 **Fast** - Processes 1000+ files per second > - 🎨 **Themeable** - 15 built-in themes or use your own CSS > - 📝 **GFM Support** - Tables, task lists, autolinks > - 🔍 **Syntax Highlighting** - 150+ languages supported > > ## Quick Start > > ```bash > # Install globally > npm install -g md2html > > # Convert a file > md2html input.md -o output.html > > # Convert with theme > md2html input.md -o output.html --theme github-dark > ``` > > ## Installation > > **Requirements:** Node.js 18+ > > ```bash > npm install -g md2html > # or > yarn global add md2html > ``` > > ## Usage > > ### Basic Conversion > ```bash > md2html README.md > # Output: README.html in same directory > ``` > > ### Options > > | Option | Description | Default | > |--------|-------------|---------| > | `-o, --output` | Output file path | `<input>.html` | > | `-t, --theme` | Theme name or CSS file | `default` | > | `-w, --watch` | Watch for changes | `false` | > | `--no-highlight` | Disable syntax highlighting | - | > > [Full documentation →](https://md2html.dev/docs) > ``` ## Related Resources - [Write the Docs](https://www.writethedocs.org/) - [Divio Documentation System](https://documentation.divio.com/) - [Google Developer Documentation Style Guide](https://developers.google.com/style) - [ReadMe Best Practices](https://readme.so/) ````