documentation

文档

此技能提供全面的文档编写能力，包括 API 文档、技术写作、变更日志生成和开发者指南。涵盖从 OpenAPI 规范到面向用户的变更日志的所有内容。

何时使用此技能

• 编写 REST API 文档或 GraphQL Schema 文档时
• 创建 OpenAPI/Swagger 规范时
• 生成客户端 SDK 时
• 编写 API 集成指南时
• 创建交互式 API 文档时
• 维护 API 版本管理和迁移指南时
• 编写用户指南和教程时
• 创建或改进 README 文件时
• 记录架构和设计决策时
• 编写代码注释和内联文档时
• 提高内容的清晰度和易读性时
• 创建入门文档时
• 编写功能规范和设计文档时
• 创建架构决策记录（ADR）时
• 记录技术决策及其依据时
• 创建版本升级迁移指南时
• 记录破坏性变更和升级路径时
• 规划并记录数据库迁移时
• 为新版本准备发行说明时
• 创建每周或每月产品更新摘要时
• 向客户说明变更时
• 为应用商店提交内容编写变更日志条目时
• 生成更新通知时
• 创建内部发行文档时
• 维护公开的变更日志／产品更新页面时

此技能的功能

1. OpenAPI 规范：创建完整的 OpenAPI 3.0/Swagger 规范
2. SDK 生成：生成客户端库和 SDK
3. 交互式文档：创建 Postman 集合和交互式文档
4. 版本管理：管理 API 版本和迁移指南
5. 代码示例：提供多种语言的示例
6. 开发者指南：编写身份验证和集成指南
7. 用户指南：创建包含清晰说明的分步用户指南
8. 教程：编写循序渐进、逐步扩展知识的教程
9. README 文件：创建包含徽章和各类章节的完整 README 文件
10. 架构文档：记录系统架构和设计决策
11. 代码文档：编写清晰的代码注释和内联文档
12. 内容组织：通过清晰的标题和行文结构组织内容
13. 变更日志生成：将 git 提交记录转化为用户易读的变更日志
14. 设计规范：创建功能规范和技术设计文档
15. ADR：记录架构决策记录及其背景和影响
16. 迁移指南：创建包含回滚流程的分步迁移文档

使用方法

编写 API 文档

Create OpenAPI specification for this API

Generate API documentation for the /api/users endpoints

编写文档

Create a user guide for this feature

Write a README for this project

生成变更日志

Create a changelog from commits since last release

Generate changelog for all commits from the past week

API 文档

开发过程中同步编写文档

• 在开发过程中编写 API 文档，而不是事后补写
• 确保文档与代码保持同步
• 优先使用真实示例，而非抽象描述
• 展示成功和错误两种情况
• 为所有内容（包括文档）进行版本管理

OpenAPI 规范

结构：

• API 元数据（标题、版本、描述）
• 服务端定义
• 安全方案
• 路径和操作
• 请求／响应 Schema
• 所有操作的示例

示例：

openapi: 3.0.0
info:
  title: User API
  version: 1.0.0
  description: API for user management

paths:
  /users:
    get:
      summary: List users
      responses:
        '200':
          description: List of users
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/User'

SDK 生成

支持的语言：

• JavaScript/TypeScript
• Python
• Java
• Go
• Ruby
• PHP

工具：

• OpenAPI Generator
• Swagger Codegen
• SDK 生成器

代码示例

提供多种语言的示例：

• JavaScript/Node.js
• Python
• cURL
• Ruby
• Java

技术写作

面向读者写作

• 了解读者的技能水平
• 使用恰当的术语
• 在需要时提供背景信息
• 假设读者几乎没有相关基础知识
• 加入故障排查章节

以成果为先

• 从用户将实现的目标入手
• 先展示价值，再介绍步骤
• 使用清晰、以行动为导向的语言
• 关注用户成功，而非功能

使用主动语态

• 优先使用主动语态，而非被动语态
• 使用清晰、简洁的语言
• 尽可能避免术语
• 提供真实示例和场景
• 严格按照说明操作，检验说明是否有效

文档类型

用户指南：

• 概述和目标
• 前提条件
• 分步说明
• 截图或示例
• 故障排查
• 后续步骤

README 文件：

• 项目标题和描述
• 徽章（构建状态、版本、许可证）
• 功能
• 安装
• 快速入门
• 使用示例
• 贡献
• 许可证

架构文档：

• 系统概览
• 组件图
• 设计决策
• 技术选型
• 集成点
• 数据流

生成变更日志

转换 Git 提交记录

自动根据 Git 提交记录生成面向用户的变更日志，具体包括：

• 分析提交历史
• 对变更分类（功能、改进、错误修复、重大变更、安全）
• 将技术性提交转换为清晰、便于客户理解的发行说明
• 筛除内部提交（重构、测试等）

基本用法

Create a changelog from commits since last release

Generate changelog for all commits from the past week

Create release notes for version 2.5.0

指定日期范围

Create a changelog for all commits between March 1 and March 15

使用自定义指南

Create a changelog for commits since v2.4.0, using my changelog
guidelines from CHANGELOG_STYLE.md

输出示例

# Updates - Week of March 10, 2024

## ✨ New Features

- **Team Workspaces**: Create separate workspaces for different
  projects. Invite team members and keep everything organized.

- **Keyboard Shortcuts**: Press ? to see all available shortcuts.
  Navigate faster without touching your mouse.

## 🔧 Improvements

- **Faster Sync**: Files now sync 2x faster across devices
- **Better Search**: Search now includes file contents, not just titles

## 🐛 Fixes

- Fixed issue where large images wouldn't upload
- Resolved timezone confusion in scheduled posts
- Corrected notification badge count

参考文件

如需了解详细的文档模式和指南，请按需加载参考文件：

• references/api_docs.md - API 文档模式、OpenAPI 规范、SDK 生成、版本管理策略和代码示例
• references/technical_writing.md - 技术写作最佳实践、用户指南结构、README 模板、架构文档和内容组织
• references/changelogs.md - 变更日志生成模式、提交分类、面向用户的内容转换和发行说明最佳实践
• references/API_DOCUMENTATION.template.md - REST API 文档模板，包含端点、身份验证、webhook 和 SDK 示例
• references/CHANGELOG.template.md - 遵循 Keep a Changelog 格式并使用 SemVer 的变更日志模板
• references/DESIGN_SPEC.template.md - 功能规划、技术设计和实施方案的设计规范模板
• references/ARCHITECTURE_DECISION_RECORD.template.md - ADR 模板，用于记录重要架构决策及其背景和影响
• references/MIGRATION_GUIDE.template.md - 版本升级、重大变更和升级路径的迁移指南模板

处理特定类型的文档时，请加载相应的参考文件。

最佳实践

文档质量

1. 真实示例：使用实际可运行的示例，而非占位符
2. 错误情况：通过示例记录错误响应
3. 身份验证：提供清晰的身份验证设置说明
4. 版本管理：说明版本管理策略和迁移路径
5. 测试：测试所有示例，确保其可用

开发者体验

• 快速入门：提供 5 分钟快速入门指南
• 交互性：使用 Postman 或 Swagger UI 等工具
• 可搜索：确保文档可搜索
• 保持最新：根据 API 变更更新文档
• 反馈：提供开发者反馈渠道

写作指南

1. 清晰：使用简单、清晰的语言
2. 结构：使用清晰的标题组织内容
3. 示例：包含真实、可运行的示例
4. 测试：亲自测试所有说明
5. 反馈：提供用户反馈渠道

内容组织

• 层级：使用清晰的标题结构
• 导航：为较长的文档添加目录
• 搜索：确保内容可搜索
• 交叉引用：链接相关章节
• 更新：保持文档为最新状态

无障碍性

• 通俗易懂：避免不必要的术语
• 结构：使用语义化 HTML/Markdown
• 图片：为图片添加替代文本
• 格式：保持格式一致
• 示例：为不同技能水平的用户提供多个示例

变更日志最佳实践

• 从 git 仓库根目录运行
• 为聚焦的变更日志指定日期范围
• 使用 CHANGELOG_STYLE.md 以保持格式一致
• 在发布前审阅并调整生成的变更日志
• 直接将输出保存到 CHANGELOG.md

相关用例

• API 规范创建
• SDK 生成
• 开发者入门
• API 集成指南
• 版本迁移文档
• 交互式 API 探索
• 用户文档
• 开发者指南
• 架构文档
• 教程创建
• 内容改进
• 创建 GitHub 发布说明
• 撰写应用商店更新描述
• 为用户生成邮件更新
• 创建社交媒体公告帖