documentation

本技能提供较完整的文档能力，涵盖 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: 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 generators。代码示例可提供 JavaScript/Node.js、Python、cURL、Ruby、Java 等多语言版本。

技术写作要点

面向读者写作：了解其技能水平，使用恰当术语，必要时提供背景，假设读者仅有少量前置知识，包含故障排查章节。先讲结果：以用户将完成什么开头，在步骤前展示价值，使用清晰、以行动为导向的语言，关注用户成功而非功能。使用主动语态：优先主动语态，语言清晰简洁，尽量避免术语，包含真实示例与场景，按说明逐步测试。

文档类型

用户指南：概述与目标、前置条件、分步说明、截图或示例、故障排查、后续步骤。README：项目标题与描述、徽章（构建状态、版本、许可证）、功能、安装、快速开始、用法示例、贡献、许可证。架构文档：系统概述、组件图、设计决策、技术选型、集成点、数据流。

更新日志生成

通过分析提交历史、对变更分类（功能、改进、缺陷修复、破坏性变更、安全）、将技术提交转换为清晰、面向客户的发布说明、过滤内部提交（重构、测试等），自动从 git 提交创建面向用户的更新日志。

基本用法：根据上次发布以来的提交创建更新日志；生成过去一周全部提交的更新日志；为版本 2.5.0 创建发布说明。指定日期范围：为 3 月 1 日至 3 月 15 日之间的全部提交创建更新日志。自定义准则：根据 v2.4.0 以来的提交创建更新日志，使用 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（用于版本升级、破坏性变更与升级路径的迁移指南模板）。处理特定文档类型时，加载相应参考文件。

最佳实践

文档质量：使用真实可运行的示例而非占位符；记录错误响应及示例；提供清晰的认证设置说明；记录版本策略与迁移路径；测试所有示例以确保可用。开发者体验：提供 5 分钟快速开始指南；使用 Postman 或 Swagger UI 等工具实现交互；让文档可搜索；随 API 变更保持文档最新；提供开发者反馈渠道。写作准则：语言简单清晰；用清晰标题组织结构；包含真实可运行的示例；自行测试所有说明；提供用户反馈渠道。内容组织：清晰的标题层级；长文档包含目录；内容可搜索；交叉链接相关章节；保持文档更新。可访问性：避免不必要的术语；使用语义化 HTML/Markdown；图片包含替代文本；格式一致；为不同技能水平提供多个示例。更新日志最佳实践：从 git 仓库根目录运行；指定日期范围以生成聚焦的更新日志；使用 CHANGELOG_STYLE.md 保持格式一致；发布前审阅并调整生成的更新日志；将输出直接保存到 CHANGELOG.md。

技能介绍

Updates - Week of March 10, 2024

✨ New Features

🔧 Improvements

🐛 Fixes