name: documentation description: 全面的文档专家，涵盖API文档、技术写作、设计文档、迁移指南和变更日志生成。适用于创建OpenAPI/Swagger规范、生成SDK、编写用户指南、创建README文件、记录架构、编写设计规范、创建ADR、编写迁移指南或从git提交生成变更日志。处理版本控制、示例、开发者体验和面向用户的文档。 author: Joseph OBrien status: unpublished updated: ‘2025-12-23’ version: 1.0.1 tag: skill type: skill

文档编写

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

何时使用此技能

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

此技能的功能

OpenAPI规范：创建完整的OpenAPI 3.0/Swagger规范
SDK生成：生成客户端库和SDK
交互式文档：创建Postman集合和交互式文档
版本控制：管理API版本控制和迁移指南
代码示例：提供多种语言的示例
开发者指南：编写身份验证和集成指南
用户指南：创建带有清晰说明的分步用户指南
教程：编写逐步构建知识的渐进式教程
README文件：创建包含徽章和部分的全面README文件
架构文档：记录系统架构和设计决策
代码文档：编写清晰的代码注释和内联文档
内容组织：通过清晰的标题和流程构建内容
变更日志生成：将git提交转换为用户友好的变更日志
设计规范：创建功能规范和技术设计文档
ADR：记录包含上下文和后果的架构决策记录
迁移指南：创建包含回滚程序的分步迁移文档

使用方法

记录API

为此API创建OpenAPI规范

为/api/users端点生成API文档

编写文档

为此功能创建用户指南

为此项目编写README

生成变更日志

从上一次发布以来的提交创建变更日志

为过去一周的所有提交生成变更日志

API文档

边构建边记录

在开发期间记录API，而不是之后
保持文档与代码同步
使用真实示例而非抽象描述
展示成功和错误案例
对所有内容（包括文档）进行版本控制

OpenAPI规范

结构：

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

示例：

openapi: 3.0.0
info:
  title: 用户API
  version: 1.0.0
  description: 用户管理API

paths:
  /users:
    get:
      summary: 列出用户
      responses:
        '200':
          description: 用户列表
          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提交自动创建面向用户的变更日志：

分析提交历史
分类变更（功能、改进、错误修复、重大变更、安全）
将技术性提交转换为清晰、客户友好的发布说明
过滤掉内部提交（重构、测试等）

基本用法

从上一次发布以来的提交创建变更日志

为过去一周的所有提交生成变更日志

为版本2.5.0创建发布说明

使用特定日期范围

为3月1日至3月15日之间的所有提交创建变更日志

使用自定义指南

为自v2.4.0以来的提交创建变更日志，使用我的变更日志指南（来自CHANGELOG_STYLE.md）

示例输出

# 更新 - 2024年3月10日当周

## ✨ 新功能

- **团队工作区**：为不同项目创建独立工作区。邀请团队成员并保持一切井井有条。

- **键盘快捷键**：按?查看所有可用快捷键。无需触摸鼠标即可更快导航。

## 🔧 改进

- **更快同步**：文件现在跨设备同步速度提高2倍
- **更好搜索**：搜索现在包括文件内容，而不仅仅是标题

## 🐛 修复

- 修复了大图片无法上传的问题
- 解决了计划帖子中的时区混淆问题
- 更正了通知徽章计数

参考文件

如需详细的文档模式和指导，请根据需要加载参考文件：

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 - 用于版本升级、重大变更和升级路径的迁移指南模板

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

最佳实践

文档质量

真实示例：使用实际工作示例，而非占位符
错误案例：记录带有示例的错误响应
身份验证：清晰的身份验证设置说明
版本控制：记录版本控制策略和迁移路径
测试：测试所有示例以确保其工作

开发者体验

快速开始：提供5分钟快速开始指南
交互式：使用Postman或Swagger UI等工具
可搜索：使文档可搜索
最新：保持文档与API变更同步
反馈：包含开发者提供反馈的方式

写作指南

清晰度：使用简单、清晰的语言
结构：通过清晰的标题组织
示例：包含真实、有效的示例
测试：亲自测试所有指令
反馈：包含用户提供反馈的方式

内容组织

层次结构：使用清晰的标题结构
导航：为长文档包含目录
搜索：使内容可搜索
交叉引用：链接相关部分
更新：保持文档最新

可访问性

通俗语言：避免不必要的行话
结构：使用语义HTML/Markdown
图像：为图像包含替代文本
格式化：使用一致的格式化
示例：为不同技能水平提供多个示例

变更日志最佳实践

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

文档编写专家Skill documentation