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

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.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
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

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

Workflow 2: Create README from Project

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

Workflow 3: Document Architecture

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

Workflow 4: Improve Code Comments

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

Best Practices

Be Clear and Concise: Use simple language, avoid jargon
Include Examples: Show, don't just tell
Keep Updated: Documentation should match current code
Consider Audience: Adjust detail level for target users
Use Consistent Format: Follow project conventions
Link Related Content: Cross-reference related documentation
Test Examples: Ensure code examples actually work
Use Visual Aids: Diagrams, screenshots when helpful
Document Why: Not just what, but why decisions were made
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.

About this skill

Quick Start

Core Capabilities

1. API Documentation

2. README Files

3. Code Documentation

4. Architecture Documentation

5. User Guides

Documentation Standards

Python Docstrings (Google Style)

JavaScript/TypeScript JSDoc

Java Javadoc

README Template

Quick Start

Usage

Basic Example

Advanced Usage

Configuration

Environment Variables

Configuration File

API Documentation

method(param1, param2)

Contributing

License

Support

Workflows

Workflow 1: Generate API Documentation

Workflow 2: Create README from Project

Workflow 3: Document Architecture

Workflow 4: Improve Code Comments

Best Practices

Documentation Structure

Tools and Formats

Supported Formats

Documentation Generators

When to Use This Skill

Examples

`method(param1, param2)`