home / skills / bejranonda / llm-autonomous-agent-plugin-for-claude / documentation-best-practices

documentation-best-practices skill

This skill helps generate and enforce comprehensive documentation templates, ensure APIs coverage, and improve readability across projects.

npx playbooks add skill bejranonda/llm-autonomous-agent-plugin-for-claude --skill documentation-best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.5 KB

---
name: documentation-best-practices
description: Provides templates, standards, and best practices for writing clear, comprehensive technical documentation
version: 1.0.0
---

## 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.

Overview

This skill provides templates, standards, and actionable best practices for writing clear, comprehensive technical documentation. It focuses on docstrings, API docs, README structure, and guidance for explaining complex logic. Use it to raise documentation coverage, consistency, and developer onboarding speed.

How this skill works

The skill inspects code and documentation targets, recommends docstring templates (Python Google style, JSDoc) and a standard README layout. It measures coverage goals for public APIs, internal functions, and complex logic, and suggests concrete edits and examples. Outputs are pragmatic templates and checklists you can apply directly in repositories.

When to use it

When creating or updating README files for new or existing projects
When writing or standardizing docstrings across Python or JavaScript codebases
When documenting public APIs to meet coverage and clarity goals
When explaining complex algorithms, security considerations, or design decisions
When preparing contribution guides and onboarding materials for new developers

Best practices

Document all public APIs to 100% and aim for 80%+ on internal functions
Use concise one-line summaries followed by longer details for complex behavior
Follow language-specific docstring formats (Google style for Python, JSDoc for JavaScript)
Include Args/Params, Returns, Raises/Throws, and short usage examples for each public function
Keep README sections focused: Title, Installation, Usage, API, Contributing, License

Example use cases

Generate consistent docstrings for a Python library to improve automated documentation output
Create a new project README with step-by-step installation and usage examples
Audit a codebase for missing documentation and produce prioritized tasks to reach coverage targets
Add explanatory comments for complex logic and algorithms to reduce onboarding time
Standardize API docs before a release to support client integrations and SDK generation

FAQ

What docstring style should I use for Python?

Prefer Google style for clarity and compatibility with many doc generators; include short summary, Args, Returns, and Raises.

How much documentation coverage is realistic?

Aim for 100% for public APIs and at least 80% for internal functions, with explanations for any complex logic.