Documentation Skill

When creating or updating documentation, follow these comprehensive guidelines:

Documentation Types

1. README Files

Essential for every project and major module:

#### Structure

# Project Name
Brief description (1-2 sentences)

## Features
- Key feature 1
- Key feature 2

## Installation
Step-by-step setup instructions

## Usage
Basic examples and common use cases

## Configuration
Environment variables, config files

## API Reference (if applicable)
Link to detailed API docs

## Contributing
How to contribute to the project

## License
License information

2. Code Comments

#### When to Comment

• Complex Logic: Algorithms, business rules, non-obvious decisions
• Why, Not What: Explain reasons, not obvious actions
• Public APIs: Document parameters, return values, exceptions
• TODOs: Track future work with context
• Warnings: Note gotchas, limitations, performance considerations

#### Comment Style

// Good: Explains why
// Using binary search here because the array is always sorted
// and can contain millions of items (requirements doc §3.2)

// Bad: States the obvious
// Loop through the array

3. API Documentation

For each endpoint/function:

• Purpose: What it does
• Parameters: Name, type, required/optional, description, constraints
• Return Value: Type, structure, possible values
• Errors: What can go wrong, error codes
• Examples: Real-world usage examples
• Authentication: Required permissions/tokens
• Rate Limits: If applicable

#### Example Format (REST API)

### GET /api/users/:id

Retrieve a user by ID.

**Parameters:**
- `id` (string, required): User UUID

**Response:** 200 OK

{ "id": "abc123", "name": "John Doe", "email": "[email protected]" }

**Errors:**
- 404: User not found
- 401: Unauthorized

**Example:**

curl -H "Authorization: Bearer token" https://api.example.com/api/users/abc123

4. Architecture Documentation

#### Key Elements

• System Overview: High-level architecture diagram
• Components: Major system components and responsibilities
• Data Flow: How data moves through the system
• Dependencies: External services, databases, libraries
• Deployment: How the system is deployed
• Security: Authentication, authorization, data protection
• Scalability: How the system scales

#### Document Patterns

• Architecture patterns used (MVC, microservices, etc.)
• Design patterns and where they're applied
• Important architectural decisions and rationale

5. User Guides

For end-users:

• Getting Started: Quick start guide
• Tutorials: Step-by-step walkthroughs
• How-To Guides: Task-oriented instructions
• Troubleshooting: Common issues and solutions
• FAQ: Frequently asked questions
• Glossary: Term definitions

Documentation Best Practices

Writing Style

• Clear: Use simple language, short sentences
• Concise: Remove unnecessary words
• Active Voice: "The function returns" not "is returned by"
• Present Tense: "Creates a user" not "will create"
• Consistent: Use same terms throughout
• Accessible: Avoid jargon, or explain it

Structure

• Progressive Disclosure: Start simple, add detail
• Logical Flow: Organize information intuitively
• Scannable: Use headings, lists, code blocks
• Search-Friendly: Use clear, descriptive headings

Maintenance

• Keep Updated: Update docs with code changes
• Version Control: Track docs with code
• Review: Include docs in code reviews
• Test: Verify examples and instructions work

Visual Aids

• Diagrams: Architecture, flow charts, sequence diagrams
• Screenshots: UI documentation
• Code Examples: Realistic, working examples
• Tables: Comparisons, parameter lists

Tools and Formats

Documentation Tools

• Markdown: README, general docs (.md)
• JSDoc/JavaDoc: Inline code documentation
• Swagger/OpenAPI: API specifications
• Mermaid: Diagrams in markdown
• Docusaurus/GitBook: Documentation sites

Diagram Tools

• Mermaid: Text-based diagrams in markdown
• PlantUML: UML diagrams from text
• Draw.io: Visual diagramming

Documentation Checklist

When creating documentation:

• [ ] Purpose is clear
• [ ] Audience is appropriate
• [ ] Examples are included
• [ ] Prerequisites are listed
• [ ] Steps are numbered and clear
• [ ] Common issues are addressed
• [ ] Links are working
• [ ] Code examples are tested
• [ ] Spelling and grammar checked
• [ ] Diagrams are clear and labeled
• [ ] Contact info or support channel included

Output Format

When generating documentation:

1. Determine the type: What kind of documentation is needed?
2. Understand the audience: Developers, end-users, admins?
3. Structure appropriately: Use the right format for the content
4. Include examples: Real, working examples
5. Add visuals: Diagrams or code snippets where helpful
6. Review for clarity: Is this understandable to the target audience?