documentation-best-practices

Overview

This skill provides guidelines for creating high-quality documentation including docstrings, API documentation, README files, and usage guides.

Documentation Coverage Targets

• Public APIs: 100% documented
• Internal Functions: 80%+ documented
• Complex Logic: Must have explanation comments
• Overall: 85%+ coverage

Docstring Templates

Python (Google Style)

def function_name(param1: str, param2: int) -> bool:
    """Brief one-line description.

    Longer detailed explanation if needed.

    Args:
        param1: Description of param1
        param2: Description of param2

    Returns:
        Description of return value

    Raises:
        ValueError: When and why
    """

JavaScript (JSDoc)

/**
 * Brief one-line description.
 *
 * @param {string} param1 - Description of param1
 * @param {number} param2 - Description of param2
 * @returns {boolean} Description of return value
 * @throws {Error} When and why
 */

README Structure

1. Project Title & Description
2. Installation: Step-by-step setup
3. Usage: Basic examples
4. API Documentation: Overview or link
5. Contributing: Guidelines (if applicable)
6. License: Project license

When to Apply

Use when generating documentation, updating docstrings, creating README files, or maintaining API documentation.