Documentation Skill

Documentation Skill

Create clear, comprehensive, and maintainable documentation for code projects.

Documentation Types

1. README.md

Purpose: Project overview and quick start guide

Essential Sections:

# Project Name

Brief description (1-2 sentences)

## Features
- Key feature 1
- Key feature 2

## Installation
```bash
npm install package-name

Quick Start

const lib = require('package-name');
lib.doSomething();

Usage

[Detailed examples]

API Reference

[Link to detailed API docs]

Contributing

[How to contribute]

License

MIT

---

### 2. Code Comments

**When to Comment**:
- ✅ Complex algorithms
- ✅ Non-obvious decisions
- ✅ Workarounds for bugs
- ✅ Public APIs
- ❌ Self-explanatory code
- ❌ What code does (code shows that)

**Good Comments**:
```python
# Calculate tax using 2024 progressive rates
# See: https://irs.gov/​tax-rates-2024
def calculate_tax(income):
    # ...

# HACK: API returns string "null" instead of null
# TODO: Remove once API v2 is deployed
if response == "null":
    response = None

Bad Comments:

# Increment i
i = i + 1  # Obvious from code

# This function adds two numbers
def add(a, b):  # Function name is clear
    return a + b

---

3. Function Documentation

Python (Docstrings):

def calculate_discount(price: float, discount_pct: float) -> float:
    """
    Calculate discounted price.

    Args:
        price: Original price in dollars
        discount_pct: Discount percentage (0-100)

    Returns:
        Final price after discount

    Raises:
        ValueError: If discount_pct is not between 0 and 100

    Examples:
        >>> calculate_discount(100, 20)
        80.0
    """
    if not 0 <= discount_pct <= 100:
        raise ValueError("Discount must be between 0 and 100")
    return price * (1 - discount_pct / 100)

JavaScript (JSDoc):

/​**
 * Calculate discounted price
 * @param {number} price - Original price in dollars
 * @param {number} discountPct - Discount percentage (0-100)
 * @returns {number} Final price after discount
 * @throws {Error} If discountPct is not between 0 and 100
 * @example
 * calculateDiscount(100, 20) // Returns 80
 */
function calculateDiscount(price, discountPct) {
    if (discountPct < 0 || discountPct > 100) {
        throw new Error('Discount must be between 0 and 100');
    }
    return price * (1 - discountPct / 100);
}

---

4. API Documentation

REST API Example:

## GET /​api/​users/:id

Retrieve user by ID.

### Parameters
- `id` (path, required): User ID

### Query Parameters
- `include` (optional): Comma-separated relations to include
  - Values: `profile`, `posts`, `comments`

### Response
```json
{
  "id": 123,
  "name": "John Doe",
  "email": "[email protected]",
  "createdAt": "2024-01-15T10:30:00Z"
}

Status Codes

• 200 OK: User found
• 404 Not Found: User doesn't exist
• 401 Unauthorized: Missing or invalid token

Example

curl -H "Authorization: Bearer TOKEN" \
     https://api.example.com/api/users/123?include=profile

---

### 5. Architecture Documentation

**System Overview**:
```markdown
## Architecture

### High-Level Design

┌──────────┐ ┌──────────┐ ┌──────────┐ │ Client │─────▶│ API │─────▶│ Database │ └──────────┘ └──────────┘ └──────────┘ │ ▼ ┌──────────┐ │ Cache │ └──────────┘

### Components

#### API Server
- **Technology**: Node.js + Express
- **Responsibility**: Handle HTTP requests, business logic
- **Scaling**: Horizontal (load balanced)

#### Database
- **Technology**: PostgreSQL 15
- **Responsibility**: Persistent data storage
- **Backup**: Daily automated backups

#### Cache
- **Technology**: Redis
- **Responsibility**: Session storage, API response cache
- **TTL**: 5 minutes for API responses

---

Documentation Best Practices

Writing Guidelines

1. Be Clear and Concise

   • Use simple language
   • Avoid jargon (or explain it)
   • Short sentences and paragraphs

2. Use Examples

   • Show don't just tell
   • Include common use cases
   • Provide working code samples

3. Keep Updated

   • Update docs with code changes
   • Mark deprecated features
   • Version documentation

4. Structure Logically

   • Start with overview
   • Organize by use case
   • Use clear headings

5. Make Searchable

   • Use descriptive headings
   • Include keywords
   • Add table of contents

Format Tips

Use Code Blocks:

```python
# Code here
```

Use Tables:

| Parameter | Type   | Required | Description |
|-----------|--------|----------|-------------|
| name      | string | yes      | User name   |

Use Lists:

- Item 1
- Item 2
  - Sub-item 2.1

Use Emphasis:

**Bold** for important terms
*Italic* for emphasis
`code` for inline code

---

Documentation Templates

README Template

# Project Name

One-line description

## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Usage](#usage)
- [API Reference](#api-reference)
- [Contributing](#contributing)
- [License](#license)

## Features
- Feature 1
- Feature 2

## Installation

### Prerequisites
- Node.js 18+
- npm or yarn

### Steps
```bash
git clone https://github.com/user/repo.git
cd repo
npm install

Usage

Basic Example

const lib = require('lib');
lib.doSomething();

Advanced Example

[More complex usage]

API Reference

See API.md for detailed API documentation.

Configuration

Create .env file:

API_KEY=your_key
DATABASE_URL=postgresql://...

Development

npm run dev        # Start dev server
npm test          # Run tests
npm run lint      # Lint code

Contributing

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

License

MIT License - see LICENSE file

Contact

• GitHub: @username
• Email: [email protected]

### CHANGELOG Template
```markdown
# Changelog

All notable changes to this project will be documented in this file.

The format is based on [Keep a Changelog](https://keepachangelog.com/).

## [Unreleased]

### Added
- New feature X

### Changed
- Updated dependency Y

### Fixed
- Bug Z in component W

## [1.0.0] - 2024-01-15

### Added
- Initial release
- Feature A
- Feature B

### Security
- Fixed vulnerability CVE-XXXX

CONTRIBUTING Template

# Contributing Guide

Thank you for contributing!

## Code of Conduct

Be respectful and inclusive.

## How to Contribute

### Reporting Bugs
- Check existing issues first
- Use bug report template
- Include reproduction steps
- Specify environment details

### Suggesting Features
- Check roadmap and existing requests
- Use feature request template
- Explain use case and benefits

### Pull Requests

#### Before Submitting
1. Fork and create branch
2. Follow coding standards
3. Add tests
4. Update documentation
5. Run linter and tests

#### PR Guidelines
- Clear description of changes
- Link related issues
- Keep changes focused
- Update CHANGELOG.md

## Development Setup

```bash
git clone https://github.com/user/repo.git
cd repo
npm install
npm run dev

Testing

npm test              # Run all tests
npm run test:watch    # Watch mode
npm run test:coverage # Coverage report

Code Style

• Follow ESLint configuration
• Use Prettier for formatting
• Write descriptive commit messages

Commit Messages

Format: type(scope): description

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation
• style: Formatting
• refactor: Code restructure
• test: Tests
• chore: Maintenance

Example: feat(auth): add password reset

---

## Documentation Checklist

Before finalizing documentation:

- [ ] README exists and is complete
- [ ] Installation instructions clear
- [ ] Usage examples provided
- [ ] API documented (if applicable)
- [ ] Code has appropriate comments
- [ ] Complex logic explained
- [ ] Configuration documented
- [ ] Contributing guide exists
- [ ] License specified
- [ ] CHANGELOG maintained
- [ ] Links work correctly
- [ ] Code examples tested
- [ ] Spelling/​grammar checked
- [ ] Formatting consistent

---

## Automation Tips

### Auto-Generate API Docs
```javascript
// JSDoc to Markdown
npm install -g jsdoc-to-markdown
jsdoc2md src/​**/​*.js > API.md

Documentation Testing

# Python: Test docstring examples
python -m doctest module.py

# Or use pytest
pytest --doctest-modules

Keep Docs in Sync

# Pre-commit hook to check docs
#!/​bin/​bash
if git diff --cached --name-only | grep -q "^src/"; then
    if ! git diff --cached --name-only | grep -q "^docs/"; then
        echo "Warning: Code changed but docs not updated"
        exit 1
    fi
fi

---

Remember

• Documentation is part of the code
• Good docs save time for everyone
• Update docs with every code change
• Write for your future self
• Examples are worth a thousand words