Documentation

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

```bash
# 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

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.

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 file for details.

Support

• Documentation: [link]
• Issues: [link]
• Discussions: [link]

## Architecture Decision Records (ADR)

Template for documenting architecture decisions:

```markdown
# 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 for complete documentation examples across different project types and languages.

For documentation templates, see templates/.

For automated documentation generation, see scripts/generate_docs.py.