# Documentation Best Practices

> Provides templates, standards, and best practices for writing clear, comprehensive technical documentation

- Skill: `majiayu000/documentation-best-practices` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/documentation-best-practices`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/documentation-best-practices/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/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)
```python
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)
```javascript
/**
 * 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.