Documentation

A comprehensive documentation skill that helps create, maintain, and improve technical documentation across various formats and purposes.

Quick Start

Basic documentation workflow:

# Read existing code/project structure
# Identify documentation needs
# Generate appropriate documentation format
# Include examples and usage patterns

Core Capabilities

1. API Documentation

Generate comprehensive API documentation:

• REST APIs: Endpoints, parameters, responses, examples
• Function/Method Documentation: Parameters, return values, exceptions
• Type Definitions: Interfaces, classes, data structures
• Authentication: Auth methods, security considerations
• Error Handling: Status codes, error messages, troubleshooting

2. README Files

Create clear and complete README files:

• Project Overview: Purpose, features, benefits
• Installation: Prerequisites, setup steps, configuration
• Quick Start: Minimal example to get started
• Usage Examples: Common use cases with code samples
• Configuration: Environment variables, config files
• Contributing: Guidelines for contributors
• License: License information

3. Code Documentation

Improve inline code documentation:

• Docstrings: Function/class documentation following conventions
• Comments: Explanatory comments for complex logic
• Type Hints: Type annotations (Python, TypeScript)
• JSDoc: JavaScript documentation comments
• Javadoc: Java documentation comments

4. Architecture Documentation

Document system architecture:

• Architecture Diagrams: System components and relationships
• Design Decisions: ADRs (Architecture Decision Records)
• Data Flow: How data moves through the system
• Technology Stack: Technologies used and why
• Deployment: Infrastructure and deployment processes

5. User Guides

Create user-facing documentation:

• Getting Started: First steps for new users
• Tutorials: Step-by-step learning paths
• How-To Guides: Task-focused instructions
• Reference: Complete feature documentation
• Troubleshooting: Common issues and solutions

Documentation Standards

Python Docstrings (Google Style)

def calculate_total(items: list[dict], tax_rate: float = 0.1) -> float:
    """Calculate total price including tax for a list of items.
    
    Takes a list of items with prices and calculates the total cost
    including the specified tax rate.
    
    Args:
        items: List of item dictionaries with 'price' keys
        tax_rate: Tax rate as decimal (default: 0.1 for 10%)
    
    Returns:
        Total price including tax, rounded to 2 decimal places
    
    Raises:
        ValueError: If items list is empty or contains invalid prices
        TypeError: If items is not a list
    
    Examples:
        >>> items = [{'price': 10.0}, {'price': 20.0}]
        >>> calculate_total(items)
        33.0
        
        >>> calculate_total(items, tax_rate=0.2)
        36.0
    """
    if not isinstance(items, list):
        raise TypeError("items must be a list")
    if not items:
        raise ValueError("items list cannot be empty")
    
    subtotal = sum(item['price'] for item in items)
    total = subtotal * (1 + tax_rate)
    return round(total, 2)

JavaScript/TypeScript JSDoc

/**
 * Fetches user data from the API with error handling and caching
 * 
 * @param {string} userId - The unique identifier for the user
 * @param {Object} options - Configuration options
 * @param {boolean} options.useCache - Whether to use cached data (default: true)
 * @param {number} options.timeout - Request timeout in milliseconds (default: 5000)
 * 
 * @returns {Promise<User>} Promise resolving to User object
 * 
 * @throws {UserNotFoundError} When user doesn't exist
 * @throws {NetworkError} When network request fails
 * @throws {TimeoutError} When request exceeds timeout
 * 
 * @example
 * // Basic usage
 * const user = await fetchUser('user123');
 * 
 * @example
 * // With options
 * const user = await fetchUser('user123', {
 *   useCache: false,
 *   timeout: 10000
 * });
 */
async function fetchUser(
  userId: string,
  options: FetchOptions = {}
): Promise<User> {
  // Implementation...
}

Java Javadoc

/**
 * Processes payment transactions with validation and fraud detection.
 * 
 * <p>This method validates the payment details, checks for fraudulent activity,
 * and processes the transaction through the payment gateway. All operations
 * are performed within a database transaction for consistency.
 * 
 * @param payment the payment details including amount and method
 * @param customer the customer making the payment
 * @return a {@link PaymentResult} containing transaction ID and status
 * 
 * @throws InsufficientFundsException if the payment amount exceeds available funds
 * @throws FraudDetectedException if the transaction is flagged as fraudulent
 * @throws PaymentGatewayException if the payment gateway returns an error
 * 
 * @see PaymentValidator
 * @see FraudDetector
 * @since 2.0
 * 
 * @example
 * <pre>
 * Payment payment = new Payment(100.0, PaymentMethod.CREDIT_CARD);
 * Customer customer = customerService.findById("customer123");
 * PaymentResult result = paymentProcessor.process(payment, customer);
 * System.out.println("Transaction ID: " + result.getTransactionId());
 * </pre>
 */
public PaymentResult process(Payment payment, Customer customer)
    throws InsufficientFundsException, FraudDetectedException, PaymentGatewayException {
    // Implementation...
}

README Template

Use this template for comprehensive README files:

# Project Name

Brief description of what this project does and why it's useful.

[![Build Status](badge-url)](link)
[![Coverage](badge-url)](link)
[![License](badge-url)](link)

## Features

- 🚀 Feature 1: Description
- 📦 Feature 2: Description
- 🔒 Feature 3: Description

## Table of Contents

- [Installation](#installation)
- [Quick Start](#quick-start)
- [Usage](#usage)
- [Configuration](#configuration)
- [API Documentation](#api-documentation)
- [Contributing](#contributing)
- [License](#license)

## Installation

### Prerequisites

- Node.js >= 14.0.0
- Python >= 3.8
- PostgreSQL >= 12

### Setup

Clone the repository

git clone https://github.com/username/project.git

Install dependencies

npm install

Configure environment

cp .env.example .env

Edit .env with your settings

Run migrations

npm run migrate

Start development server

npm run dev

## Quick Start

Here's a minimal example to get you started:

const Client = require('project-name');

const client = new Client({ apiKey: 'your-api-key' });

const result = await client.doSomething(); console.log(result);

## Usage

### Basic Example

[Detailed example with explanation]

### Advanced Usage

[Complex example showing advanced features]

## Configuration

### Environment Variables

| Variable | Description | Default | Required |
|----------|-------------|---------|----------|
| `API_KEY` | Your API key | - | Yes |
| `PORT` | Server port | 3000 | No |
| `DATABASE_URL` | Database connection | - | Yes |

### Configuration File

{ "setting1": "value1", "setting2": "value2" }

## API Documentation

### `method(param1, param2)`

Description of what the method does.

**Parameters:**
- `param1` (string): Description
- `param2` (number): Description

**Returns:** Description of return value

**Example:**

const result = client.method('value', 42);

## Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md).

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

This project is licensed under the MIT License - see [LICENSE](LICENSE) file for details.

## Support

- Documentation: [link]
- Issues: [link]
- Discussions: [link]

Architecture Decision Records (ADR)

Template for documenting architecture decisions:

# ADR-001: [Title]

## Status
[Proposed | Accepted | Deprecated | Superseded]

## Context
What is the issue we're facing? What are the constraints?

## Decision
What decision are we making? What alternative did we choose?

## Consequences
What are the positive and negative consequences of this decision?

### Positive
- Benefit 1
- Benefit 2

### Negative
- Trade-off 1
- Trade-off 2

### Neutral
- Consideration 1

## Alternatives Considered

### Alternative 1
- Description
- Why it was rejected

### Alternative 2
- Description
- Why it was rejected

## References
- Link to relevant discussions
- Link to related documentation

Workflows

Workflow 1: Generate API Documentation

1. Analyze Code: Identify all public APIs, functions, classes
2. Extract Information: Parameters, return types, exceptions
3. Generate Examples: Realistic usage examples
4. Format Documentation: Following language conventions
5. Add Cross-References: Link related functions/classes

Workflow 2: Create README from Project

1. Scan Project Structure: Files, dependencies, scripts
2. Identify Key Features: Main functionality
3. Extract Setup Requirements: Dependencies, environment
4. Find Usage Examples: Test files, examples directory
5. Generate Sections: Installation, usage, configuration
6. Add Badges: Build status, coverage, version

Workflow 3: Document Architecture

1. Identify Components: Services, modules, databases
2. Map Relationships: Dependencies, data flow
3. Document Decisions: Why things are designed this way
4. Create Diagrams: System architecture, data flow
5. Add Context: Technology choices, trade-offs

Workflow 4: Improve Code Comments

1. Analyze Code: Identify complex sections
2. Identify Documentation Gaps: Missing or unclear docs
3. Add Docstrings: Functions without documentation
4. Clarify Complex Logic: Add explanatory comments
5. Update Existing Docs: Fix outdated documentation

Best Practices

1. Be Clear and Concise: Use simple language, avoid jargon
2. Include Examples: Show, don't just tell
3. Keep Updated: Documentation should match current code
4. Consider Audience: Adjust detail level for target users
5. Use Consistent Format: Follow project conventions
6. Link Related Content: Cross-reference related documentation
7. Test Examples: Ensure code examples actually work
8. Use Visual Aids: Diagrams, screenshots when helpful
9. Document Why: Not just what, but why decisions were made
10. Make Discoverable: Clear organization and search

Documentation Structure

docs/
├── README.md                 # Project overview
├── CONTRIBUTING.md          # Contribution guidelines
├── CHANGELOG.md             # Version history
├── architecture/
│   ├── overview.md         # System architecture
│   ├── adr/                # Architecture decisions
│   │   ├── 001-database-choice.md
│   │   └── 002-api-design.md
│   └── diagrams/           # Architecture diagrams
├── api/
│   ├── reference.md        # Complete API reference
│   └── examples.md         # API usage examples
├── guides/
│   ├── getting-started.md  # Quick start guide
│   ├── tutorials/          # Step-by-step tutorials
│   └── how-to/             # Task-specific guides
└── reference/
    ├── configuration.md    # Configuration reference
    └── troubleshooting.md  # Common issues

Tools and Formats

Supported Formats

• Markdown: README, documentation files
• reStructuredText: Python projects (Sphinx)
• AsciiDoc: Complex documentation
• OpenAPI/Swagger: REST API documentation
• GraphQL Schema: GraphQL API documentation

Documentation Generators

• Sphinx: Python documentation
• JSDoc: JavaScript documentation
• Javadoc: Java documentation
• GoDoc: Go documentation
• Rustdoc: Rust documentation
• Swagger/OpenAPI: API documentation
• MkDocs: Project documentation sites

When to Use This Skill

Use this skill when:

• Creating new project documentation
• Writing or updating README files
• Documenting APIs or functions
• Creating user guides or tutorials
• Recording architecture decisions
• Improving code comments
• Generating API reference documentation
• Documenting deployment processes
• Creating troubleshooting guides
• Writing contributing guidelines

Examples

See [EXAMPLES.md](EXAMPLES.md) for complete documentation examples across different project types and languages.

For documentation templates, see [templates/](templates/).

For automated documentation generation, see [scripts/generatedocs.py](scripts/generatedocs.py).