documentation-best-practices
Provides templates, standards, and best practices for writing clear, comprehensive technical documentation
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for generating high-quality technical documentation, offering standardized templates for README files, API documentation, and code docstrings. It helps developers and technical writers maintain consistency, improve project maintainability, and ensure that complex logic and public APIs meet professional documentation standards.
Use Cases
- Standardizing source code documentation by generating Google-style Python docstrings or JSDoc comments for JavaScript functions.
- Creating structured and professional README.md files for new projects to improve developer onboarding and project clarity.
- Auditing existing codebases to identify documentation gaps and applying best practices to ensure high coverage of public and internal APIs.
- Establishing clear technical writing guidelines and templates for engineering teams to maintain a consistent voice and format across all project assets.
| 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)
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
- Project Title & Description
- Installation: Step-by-step setup
- Usage: Basic examples
- API Documentation: Overview or link
- Contributing: Guidelines (if applicable)
- License: Project license
When to Apply
Use when generating documentation, updating docstrings, creating README files, or maintaining API documentation.