documentation

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Documentation

文档制作

This skill provides comprehensive documentation capabilities including API documentation, technical writing, changelog generation, and developer guides. It covers everything from OpenAPI specifications to user-facing changelogs.

本技能提供全方位的文档制作能力，包括API文档、技术写作、变更日志生成及开发者指南。覆盖从OpenAPI规范到面向用户的变更日志等各类文档场景。

When to Use This Skill

适用场景

When documenting REST APIs or GraphQL schemas
When creating OpenAPI/Swagger specifications
When generating client SDKs
When writing API integration guides
When creating interactive API documentation
When maintaining API versioning and migration guides
When writing user guides and tutorials
When creating or improving README files
When documenting architecture and design decisions
When writing code comments and inline documentation
When improving content clarity and accessibility
When creating getting started documentation
When writing feature specifications and design documents
When creating Architecture Decision Records (ADRs)
When documenting technical decisions and their rationale
When creating migration guides for version upgrades
When documenting breaking changes and upgrade paths
When planning and documenting database migrations
When preparing release notes for a new version
When creating weekly or monthly product update summaries
When documenting changes for customers
When writing changelog entries for app store submissions
When generating update notifications
When creating internal release documentation
When maintaining a public changelog/product updates page

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

What This Skill Does

技能功能

OpenAPI Specs: Creates complete OpenAPI 3.0/Swagger specifications
SDK Generation: Generates client libraries and SDKs
Interactive Docs: Creates Postman collections and interactive docs
Versioning: Manages API versioning and migration guides
Code Examples: Provides examples in multiple languages
Developer Guides: Writes authentication and integration guides
User Guides: Creates step-by-step user guides with clear instructions
Tutorials: Writes progressive tutorials that build knowledge
README Files: Creates comprehensive README files with badges and sections
Architecture Docs: Documents system architecture and design decisions
Code Documentation: Writes clear code comments and inline docs
Content Organization: Structures content with clear headings and flow
Changelog Generation: Transforms git commits into user-friendly changelogs
Design Specs: Creates feature specifications and technical design documents
ADRs: Documents Architecture Decision Records with context and consequences
Migration Guides: Creates step-by-step migration documentation with rollback procedures

OpenAPI规范制作：生成完整的OpenAPI 3.0/Swagger规范
SDK生成：生成客户端库及SDK
交互式文档：创建Postman集合及交互式文档
版本管理：管理API版本及迁移指南
代码示例：提供多语言代码示例
开发者指南：编写认证及集成指南
用户指南：创建步骤清晰的用户指南
教程编写：撰写循序渐进的知识教程
README文件：创建包含徽章及多模块的完整README文件
架构文档：记录系统架构及设计决策
代码文档：编写清晰的代码注释及内联文档
内容组织：通过清晰的标题和流程结构化内容
变更日志生成：将Git提交记录转换为用户友好的变更日志
设计规格书：创建功能规格书及技术设计文档
ADRs制作：记录包含背景及影响的架构决策记录
迁移指南：创建包含回滚流程的分步迁移文档

How to Use

使用方法

Document API

文档化API

Create OpenAPI specification for this API

Generate API documentation for the /api/users endpoints

Create OpenAPI specification for this API

Generate API documentation for the /api/users endpoints

Write Documentation

编写文档

Create a user guide for this feature

Write a README for this project

Create a user guide for this feature

Write a README for this project

Generate Changelog

生成变更日志

Create a changelog from commits since last release

Generate changelog for all commits from the past week

Create a changelog from commits since last release

Generate changelog for all commits from the past week

API Documentation

API文档制作

Document as You Build

边开发边文档化

Document APIs during development, not after
Keep documentation in sync with code
Use real examples over abstract descriptions
Show both success and error cases
Version everything including docs

在开发过程中同步编写API文档，而非事后补充
保持文档与代码同步更新
使用真实示例而非抽象描述
同时展示成功与错误场景
对所有内容（包括文档）进行版本管理

OpenAPI Specification

OpenAPI规范

Structure:

API metadata (title, version, description)
Server definitions
Security schemes
Paths and operations
Request/response schemas
Examples for all operations

Example:

yaml

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'

结构：

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

示例：

yaml

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 Generation

SDK生成

Supported Languages:

JavaScript/TypeScript
Python
Java
Go
Ruby
PHP

Tools:

OpenAPI Generator
Swagger Codegen
SDK generators

支持语言：

JavaScript/TypeScript
Python
Java
Go
Ruby
PHP

工具：

OpenAPI Generator
Swagger Codegen
SDK生成器

Code Examples

代码示例

Provide examples in multiple languages:

JavaScript/Node.js
Python
cURL
Ruby
Java

提供多语言示例：

JavaScript/Node.js
Python
cURL
Ruby
Java

Technical Writing

技术写作

Write for Your Audience

面向目标受众写作

Know their skill level
Use appropriate terminology
Provide context when needed
Assume minimal prior knowledge
Include troubleshooting sections

了解受众技能水平
使用恰当的术语
必要时提供背景信息
假设用户仅有基础前置知识
包含故障排除章节

Lead with the Outcome

以结果为导向

Start with what users will accomplish
Show the value before the steps
Use clear, action-oriented language
Focus on user success, not features

开篇说明用户将达成的目标
先展示价值再介绍步骤
使用清晰、面向行动的语言
聚焦用户成功而非功能本身

Use Active Voice

使用主动语态

Prefer active over passive voice
Use clear, concise language
Avoid jargon when possible
Include real examples and scenarios
Test instructions by following them exactly

优先使用主动语态而非被动语态
使用简洁明了的语言
尽可能避免行话
包含真实示例与场景
严格按照说明步骤测试验证

Documentation Types

文档类型

User Guides:

Overview and goals
Prerequisites
Step-by-step instructions
Screenshots or examples
Troubleshooting
Next steps

README Files:

Project title and description
Badges (build status, version, license)
Features
Installation
Quick start
Usage examples
Contributing
License

Architecture Docs:

System overview
Component diagrams
Design decisions
Technology choices
Integration points
Data flow

用户指南：

概述与目标
前置条件
分步说明
截图或示例
故障排除
后续步骤

README文件：

项目标题与描述
徽章（构建状态、版本、许可证）
功能特性
安装方法
快速入门
使用示例
贡献指南
许可证

架构文档：

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

Changelog Generation

变更日志生成

Transforming Git Commits

转换Git提交记录

Automatically creates user-facing changelogs from git commits by:

Analyzing commit history
Categorizing changes (features, improvements, bug fixes, breaking changes, security)
Transforming technical commits into clear, customer-friendly release notes
Filtering out internal commits (refactoring, tests, etc.)

通过以下步骤自动将Git提交记录转换为面向用户的变更日志：

分析提交历史
分类变更类型（功能新增、改进、Bug修复、破坏性变更、安全更新）
将技术化提交信息转换为清晰易懂的发布说明
过滤内部提交记录（重构、测试等）

Basic Usage

基础用法

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 from commits since last release

Generate changelog for all commits from the past week

Create release notes for version 2.5.0

With Specific Date Range

指定日期范围

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

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

With Custom Guidelines

自定义规范

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

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

Example Output

示例输出

markdown

undefined