Back to Details

documentation-best-practices

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Overview

概述

This skill provides guidelines for creating high-quality documentation including docstrings, API documentation, README files, and usage guides.
本技能提供创建高质量文档的指南，包括文档字符串（docstrings）、API文档、README文件和使用指南。

Documentation Coverage Targets

文档覆盖目标

  • Public APIs: 100% documented
  • Internal Functions: 80%+ documented
  • Complex Logic: Must have explanation comments
  • Overall: 85%+ coverage
  • 公开API：100% 文档覆盖
  • 内部函数：80%+ 文档覆盖
  • 复杂逻辑：必须包含解释性注释
  • 整体要求：85%+ 文档覆盖

Docstring Templates

文档字符串模板

Python (Google Style)

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
    """
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 (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
 */
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

README文件结构

  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
  1. 项目标题与描述
  2. 安装步骤：分步设置指南
  3. 使用方法：基础示例
  4. API文档：概述或链接
  5. 贡献指南：贡献规则（如适用）
  6. 许可证：项目许可证

When to Apply

适用场景

Use when generating documentation, updating docstrings, creating README files, or maintaining API documentation.
适用于生成文档、更新文档字符串、创建README文件或维护API文档时使用。