⚡

技术文档管理Skill documentation

此技能用于创建和维护全面的技术文档，涵盖从代码级注释到项目级指南的所有需求，包括API文档、README文件、架构决策记录(ADR)、更新日志等，提升文档的清晰度、可访问性和可维护性，适用于软件开发团队。关键词：技术文档、API文档、README、ADR、更新日志、代码注释、文档编写、SEO优化。

其他 0 次安装 2 次浏览 更新于 3/24/2026

名称: 文档 描述: 创建和维护技术文档，包括API文档、README文件、架构文档、更新日志、ADR和代码内注释。处理所有文档需求，从代码级文档字符串到项目级指南。触发关键词: 文档, 文档编写, 记录, README, 教程, 指南, 参考, 更新日志, ADR, 架构决策记录, 文档字符串, JSDoc, rustdoc, pydoc, 标记语言, mdx, API文档, 用户指南, 开发者指南, 内联注释, 代码注释。 允许工具: 读取, 搜索, 全局匹配, 编辑, 写入

文档

概述

此技能创建清晰、全面且可维护的文档，涵盖所有级别：代码文档（文档字符串、内联注释）、API参考、架构文档、README文件、ADR、更新日志和用户指南。吸收技术写作专业知识以确保清晰度和可访问性。

说明

1. 评估文档需求

  • 确定目标受众（开发者、用户、操作员、贡献者）
  • 确定所需文档类型
  • 审查现有文档以查找差距和不一致性
  • 理解代码库结构和模式

2. 代码文档

文档字符串/文档注释：

  • 添加语言适当的文档（如JSDoc、rustdoc、pydoc等）
  • 记录目的、参数、返回值和异常
  • 在语言支持时包括类型信息
  • 为复杂函数提供使用示例
  • 解释非显而易见的行为和边缘情况

内联注释：

  • 解释为什么，而不是什么（代码已经显示是什么）
  • 记录复杂算法或业务逻辑
  • 用问题引用标记已知限制或待办事项
  • 保持注释与代码更改同步更新

3. API文档

  • 记录所有公共端点/方法
  • 包括请求/响应格式及示例
  • 提供认证和授权详情
  • 显示错误响应及状态码
  • 记录速率限制和分页
  • 包括版本信息

4. README文件

必要部分：

  • 项目名称和一行描述
  • 安装/设置说明
  • 快速入门示例
  • 核心功能概述
  • 开发设置
  • 测试说明
  • 贡献指南
  • 许可证信息

README最佳实践：

  • 将最重要信息放在前面
  • 使用清晰标题以提高可扫描性
  • 包括构建状态、版本、许可证的徽章
  • 提供可工作的代码示例
  • 需要时链接到详细文档

5. 架构决策记录 (ADR)

记录重要架构决策，包括：

  • 上下文：我们正在解决什么问题？
  • 决策：我们选择了什么？
  • 后果：权衡和影响
  • 考虑的替代方案：我们拒绝了什么及原因
  • 状态：提议、接受、弃用、被取代

6. 更新日志

遵循语义版本控制和常规提交：

  • 按类型分组更改（新增、更改、修复、移除、安全）
  • 链接到相关问题/PR
  • 突出显示重大更改
  • 为每个发布日期化
  • 使用现在时（例如，“添加功能”而非“已添加功能”）

7. 技术写作原则

清晰度：

  • 使用简单直接的语言
  • 在首次使用时定义技术术语
  • 写短句子（目标15-20词）
  • 每个段落一个想法

结构：

  • 使用一致的标题层级
  • 用子标题分割长部分
  • 使用列表表示顺序步骤或相关项
  • 为结构化比较添加表格

可访问性：

  • 避免使用行话，除非必要
  • 为抽象概念提供示例
  • 使用主动语态（例如，“运行命令”而非“命令应运行”）
  • 在有帮助时包括视觉辅助（图表、代码块）

最佳实践

  1. 为你的受众写作：根据读者专业知识匹配复杂性
  2. 保持最新：代码更改时更新文档
  3. 展示，而不仅仅是讲述：包括可工作的示例
  4. 简洁：删除不必要的词语
  5. 结构一致：使用模板和模式
  6. 解释为什么：记录决策，而不仅仅是事实
  7. 使其可搜索：使用清晰标题和关键词
  8. 测试你的示例：确保代码示例实际工作
  9. 版本化你的文档：将文档与代码版本匹配
  10. 自由链接：连接相关文档

模板

README模板

# 项目名称

一行描述此项目做什么。

## 功能

- 关键功能1
- 关键功能2
- 关键功能3

## 安装

    npm install 项目名称

## 快速入门

    const project = require('项目名称');
    project.doSomething();

## 文档

参见[完整文档](链接)获取详细使用信息。

## 开发

    npm install
    npm test
    npm run build

## 贡献

参见[CONTRIBUTING.md](CONTRIBUTING.md)。

## 许可证

MIT

ADR模板

# ADR-001: 使用事件溯源进行审计追踪

**状态：** 接受

**日期：** 2024-01-15

**上下文：**
我们需要为监管合规性维护财务记录所有更改的完整审计追踪。当前的原地更新方法丢失历史状态。

**决策：**
实现事件溯源模式，其中所有状态更改存储为不可变事件。当前状态通过重放事件派生。

**后果：**

积极方面：

- 设计上的完整审计追踪
- 时间旅行调试能力
- 监管报告的自然适应

消极方面：

- 增加的存储需求
- 查询当前状态的复杂性
- 团队学习曲线

**考虑的替代方案：**

1. 数据库触发器 + 审计表：由于触发器维护负担而拒绝
2. 更改数据捕获：由于耦合到数据库技术而拒绝
3. 手动审计日志记录：由于易出错实现而拒绝

更新日志模板

# 更新日志

此项目的所有重要更改将记录在此文件中。

格式基于[保持更新日志](https://keepachangelog.com/en/1.0.0/)，
并且此项目遵循[语义版本控制](https://semver.org/spec/v2.0.0.html)。

## [未发布]

### 新增

- 新功能描述

### 更改

- 现有功能的变化

### 修复

- 错误修复描述

## [1.2.0] - 2024-01-15

### 新增

- 用户资料管理 (#123)
- 导出到CSV功能 (#145)

### 更改

- 更新依赖到最新版本
- 改进验证失败的错误消息

### 修复

- 修复支付处理中的竞态条件 (#156)
- 更正报告中的时区处理 (#162)

示例

示例1: Python文档字符串（Google风格）

def calculate_shipping_cost(
    weight: float,
    destination: str,
    express: bool = False
) -> Decimal:
    """基于包裹重量和目的地计算运费。

    应用基于重量等级的层级定价，并为国际目的地和快递交付添加附加费。

    参数:
        weight: 包裹重量（千克）。必须为正数。
        destination: ISO 3166-1 alpha-2国家代码（例如，'US', 'GB'）。
        express: 如果为真，使用快递交付（2-3天）。默认是标准交付（5-7天）。

    返回:
        以美元计算的运费作为Decimal。

    引发:
        ValueError: 如果重量不是正数。
        InvalidDestinationError: 如果国家代码不被识别。

    示例:
        >>> calculate_shipping_cost(2.5, 'US')
        Decimal('12.50')
        >>> calculate_shipping_cost(2.5, 'GB', express=True)
        Decimal('45.00')
    """

示例2: Rust文档

/// 管理用户认证和会话处理。
///
/// 此服务处理完整的认证生命周期，包括登录、令牌验证和会话管理。令牌是具有24小时有效期的JWT。
///
/// # 示例
///
/// ```
/// use auth::AuthService;
///
/// let auth = AuthService::new(config);
/// let token = auth.login("user@example.com", "password").await?;
/// let user = auth.validate_token(&token)?;
/// ```
///
/// # 错误
///
/// 如果登录失败，返回 `AuthError::InvalidCredentials`。
/// 如果令牌验证失败，返回 `AuthError::TokenExpired`。
pub struct AuthService {
    // 字段
}

impl AuthService {
    /// 用电子邮件和密码认证用户。
    ///
    /// # 参数
    ///
    /// * `email` - 用户的电子邮件地址
    /// * `password` - 用户的密码（将在比较前进行哈希）
    ///
    /// # 返回
    ///
    /// 有效期为24小时的JWT访问令牌
    ///
    /// # 错误
    ///
    /// 如果凭据无效或账户被锁定，返回错误
    pub async fn login(&self, email: &str, password: &str) -> Result<String, AuthError> {
        // 实现
    }
}

示例3: API端点文档

## 创建用户

创建新用户账户。

**端点：** `POST /api/v1/users`

**认证：** 需要（管理员角色）

**请求体：**
| 字段 | 类型 | 必需 | 描述 |
|-----------|--------|----------|--------------------------------|
| email | 字符串 | 是 | 有效电子邮件地址 |
| name | 字符串 | 是 | 全名（2-100个字符） |
| role | 字符串 | 否 | 用户角色。默认: "member" |

**示例请求：**

    POST /api/v1/users
    Authorization: Bearer eyJhbGc...
    Content-Type: application/json

    {
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "admin"
    }

**成功响应（201 Created）：**

    {
      "id": "usr_abc123",
      "email": "jane@example.com",
      "name": "Jane Smith",
      "role": "admin",
      "createdAt": "2024-01-15T10:30:00Z"
    }

**错误响应：**
| 状态 | 代码 | 描述 |
|--------|-------------------|---------------------------------|
| 400 | INVALID_EMAIL | 电子邮件格式无效 |
| 400 | NAME_TOO_SHORT | 名称必须至少2个字符 |
| 409 | EMAIL_EXISTS | 电子邮件已注册 |
| 403 | FORBIDDEN | 权限不足 |

示例4: 内联注释（好 vs 坏）

// 坏: 陈述显而易见的事情
// 将计数器增加1
counter += 1;

// 好: 解释为什么
// 跳过第一条记录，因为它总是CSV头部
counter += 1;

// 坏: 不添加价值
// 检查用户是否有效
if user.is_valid() {

// 好: 解释非显而易见的业务规则
// 2020年之前创建的用户没有启用电子邮件验证
if user.is_valid() {

交付成果

创建文档时，交付：

  1. 完整覆盖：所有公共API、配置选项和工作流程都已文档化
  2. 可工作的示例：编译和成功运行的代码示例
  3. 清晰结构：逻辑组织，长文档有目录
  4. 最新：文档匹配当前代码行为
  5. 可访问：为目标受众写作，使用适当水平
  6. 可发现：正确文件名、清晰标题、良好SEO关键词

常见陷阱避免

  • 记录应私有的实现细节
  • 编写重复代码已表达内容的文档
  • 使用模糊语言（例如，“可能”、“通常”、“有时”）
  • 忘记在代码更改时更新文档
  • 假设读者知识而不定义术语
  • 以被动语态编写文档
  • 创建没有链接的孤立文档
  • 跳过错误情况和边缘条件