Document Writer

Write or update technical documentation for the target project at $ARGUMENTS.

Preconditions

Paths starting with <skill-dir> are relative to this skill's base directory, announced when the skill loads. Substitute that literal path; it is not an environment variable.

1. If $ARGUMENTS is empty, report: Error: Please provide the target path and the documentation task (for example: './docs/api.md update the payment API docs' or './src/utils.ts add JSDoc for the public helpers'). 2. Read <skill-dir>/references/WORKFLOW.md, <skill-dir>/references/DOCUMENT_TYPES.md, and <skill-dir>/references/VERIFICATION_CHECKLIST.md before drafting. 3. If the request is in Chinese, the output file is Chinese, or the user wants polishing/rewrite into Chinese, also read <skill-dir>/references/CHINESE_TECH_WRITING.md.

Execution Flow

1. Classify the task

Determine the closest document type before writing:

• README.md or overview docs
• API reference or endpoint documentation
• Architecture or design explanation
• User guide, operator guide, troubleshooting, FAQ
• CONTRIBUTING, maintenance, migration, or release notes
• JSDoc, docstrings, or code comments

Infer the type from the requested file, target path, and user request. Ask only if multiple document types would lead to materially different outputs.

2. Gather evidence from the codebase

Use the actual project files as the source of truth:

1. Read existing documentation first so you preserve project vocabulary and avoid duplicating stale mistakes. 2. Inspect the directory structure, entrypoints, configs, public interfaces, examples, and tests. 3. Trace important flows from input to output when documenting behavior, not just file names. 4. For API or architecture docs, verify routes, config keys, environment variables, and defaults against code. 5. For JSDoc or comments, read the concrete symbol implementation before writing anything.

3. Decide language, audience, and output location

1. Match the language requested by the user or already used by the surrounding docs. 2. If the task is a rewrite into Chinese, follow the Chinese writing reference instead of translating line by line. 3. Prefer updating the explicitly requested file in place. 4. If no exact file is given, use the conventional location:

• repository root for README.md, CONTRIBUTING.md, MIGRATION.md
• docs/ for user, API, or architecture docs
• source file for JSDoc or code comments

5. If location is still ambiguous after exploring the repo, ask one focused question.

4. Draft using the correct structure

1. Apply the matching template and required sections from DOCUMENT_TYPES.md. 2. Scale the detail to the real scope:

• small utility or module: shorter docs, fewer sections
• multi-component flow or public API: full structure with examples and failure cases

3. Organize around reader tasks, public interfaces, or data flow instead of mirroring the folder tree mechanically. 4. For architecture docs covering more than one component, include a Mermaid diagram unless the repo already uses another explicit format.

5. Generate content that can survive verification

1. Base commands, code snippets, function signatures, env vars, and config values on real files. 2. Preserve industry-standard English terms when they are clearer than forced translation. 3. In Chinese docs, prefer natural Chinese phrasing over literal translation. 4. Use TODO: only for facts that cannot be derived from the repo and are necessary for completeness. 5. For comments and JSDoc, document public contracts, side effects, invariants, errors, or non-obvious behavior. Do not add boilerplate comments that restate the code.

6. Verify before handoff

Walk through VERIFICATION_CHECKLIST.md and confirm:

• every important claim is backed by code, config, tests, or existing maintained docs
• examples and commands match the project layout
• links and file paths exist
• no secrets, tokens, private endpoints, or internal-only notes were leaked
• Chinese output follows the Chinese writing reference when applicable

Rules

• Do not fabricate APIs, CLI flags, configuration defaults, performance numbers, or implementation details.
• Do not copy stale wording from old docs without checking whether the code still matches.
• Do not translate common technical terms into unnatural Chinese when the English form is the norm.
• Keep the tone concise, direct, and professional.
• Output the documentation artifact only. Avoid extra conversational explanation unless the user explicitly asks for it.

中文技术文档写作规范

这份规范用于中文技术文档、中文 README、中文 API 文档，以及将现有技术说明重写成自然中文的场景。

核心目标不是“翻译成中文”，而是写成专业、自然、可读的中文技术文档。

1. 排版规则

中英文之间加空格

正确：

• 使用 Git 管理版本。
• 服务通过 Redis 缓存热点数据。

错误：

• 使用Git管理版本。
• 服务通过Redis缓存热点数据。

中文与数字之间加空格

正确：

• 本次发布修复了 12 个问题。
• 默认重试 3 次。

错误：

• 本次发布修复了12个问题。
• 默认重试3次。

数字与单位之间加空格，但百分比和摄氏度除外

正确：

• 文件大小限制为 5 MB。
• 超时时间为 200 ms。
• CPU 使用率 95%。
• 环境温度 32°C。

链接前后保留正常空格

正确：

• 更多细节请参考 官方文档。

2. 标点规则

中文语境优先使用全角标点

正确：

• 注意：该接口需要鉴权。
• 执行完成后，会生成报告文件。

错误：

• 注意:该接口需要鉴权.
• 执行完成后,会生成报告文件.

英文命令、代码、协议名保持半角形式

正确：

• 运行 npm install，然后执行 npm test。
• 响应格式为 JSON，状态码为 200。

3. 术语处理

保留英文的情况

• 专有名词：React、TypeScript、Redis、PostgreSQL
• 行业通用缩写：API、SDK、CLI、ORM、CI/CD
• 命令、代码、配置键：npm run dev、NODE_ENV
• 协议和标准：HTTP、JSON、REST、OpenAPI

优先中文的情况

• 通用概念：数据库、缓存、浏览器、负载均衡、版本控制
• 面向读者的说明标题和段落标题，除非技术名词保留英文更自然

首次出现的重要术语可中英对照

例如：

• 消息队列（Message Queue）
• 死信队列（Dead Letter Queue）

后续出现时可直接使用更自然的一个说法。

避免过度翻译

正确：

• 在 Controller 层做参数校验，在 Service 层处理业务逻辑。
• 使用 Redis 做 Session 缓存。

错误：

• 在“控制器层”做参数校验，在“服务层”处理业务逻辑。
• 使用“远程字典服务”做“会话”缓存。

4. 语言风格

避免机翻味

不推荐：

• 这个函数被用来计算用户折扣。
• 如果你想要获取更多信息，请参考文档。

推荐：

• 这个函数用于计算用户折扣。
• 更多信息请参考文档。

避免欧化长句

不推荐：

• 这是一个可以帮助开发者在不需要手动配置复杂构建工具链的情况下快速搭建现代化前端项目的脚手架工具。

推荐：

• 这是一个前端脚手架工具，帮助开发者快速搭建现代化项目，免去手动配置构建工具链的麻烦。

一句话只说一件事

• 优先短句。
• 长定语改成并列句。
• 能用列表表达的内容不要硬写成大段说明。

5. 结构化表达

• 流程说明优先使用步骤列表。
• 复杂关系优先使用表格或 Mermaid。
• 高密度信息优先使用“结论 + 细节”结构。
• 故障排查优先写成“症状 -> 原因 -> 解决方式”。

6. 中文文档发布前检查

• 中英文之间有空格。
• 中文与数字之间有空格。
• 中文句子使用全角标点。
• 术语前后一致，没有忽中忽英。
• 没有明显机翻味或欧化长句。
• 代码块标注了语言类型。
• 链接、路径、命令与仓库实际内容一致。

文档类型规范

按文档类型选择结构。不要把所有请求都写成一份笼统的“说明文”。

README.md

适用场景： 项目首页、仓库入口、包管理器首页说明。

推荐结构：

1. 一句话说明项目是什么、解决什么问题 2. 特性或核心能力 3. 快速开始 4. 基本用法 5. 文档入口 6. 贡献方式 7. 许可证

重点：

• 让读者在 30 秒内理解项目价值。
• 安装和最小示例必须可以直接复制运行。
• 不要把 README 写成完整设计文档；复杂细节跳转到 docs/。

API 文档

适用场景： 库、SDK、HTTP 服务、CLI 命令、配置接口。

推荐结构：

1. Overview 2. Authentication / Preconditions 3. Endpoints / Methods / Commands 4. Parameters / Flags / Fields 5. Returns / Response / Output 6. Examples 7. Errors / Failure Cases

重点：

• 字段、类型、默认值、必填项必须来自真实实现。
• 请求和响应示例要贴近真实形状，不要杜撰字段。
• 错误处理不能只写“可能失败”，要说明失败条件和处理建议。

架构文档

适用场景： 解释系统结构、模块职责、调用关系、关键设计决策。

推荐结构：

1. Overview 2. System Diagram (Mermaid) 3. Components 4. Data Flow / Request Flow 5. Key Decisions 6. Risks / Constraints / Follow-ups

重点：

• 先讲系统如何工作，再讲目录里有哪些文件。
• 图示应该帮助读者看懂调用关系，而不是装饰。
• 决策部分要写清楚背景、选择、理由和代价。

用户指南 / 运维指南

适用场景： 最终用户操作说明、部署指南、故障处理、FAQ。

推荐结构：

1. Getting Started 2. Prerequisites 3. Installation / Setup 4. First Task / First Run 5. Common Workflows 6. Troubleshooting 7. FAQ

重点：

• 按用户任务组织，而不是按内部实现组织。
• 排查步骤要能实际执行。
• 对高频错误给出“症状 -> 原因 -> 处理方式”。

CONTRIBUTING / 维护文档

适用场景： 贡献指南、开发规范、发布流程、维护者说明。

推荐结构：

1. Repo Overview 2. Local Setup 3. Development Workflow 4. Testing / Validation 5. Style / Commit / PR Rules 6. Release or Maintenance Notes

重点：

• 基于仓库现有脚本、命令和流程。
• 不要发明仓库里没有的 CI、分支策略或发布步骤。
• 维护文档要服务协作，不要只罗列规范。

迁移说明 / 变更说明

适用场景： 版本升级、破坏性变更、配置迁移、接口替换。

推荐结构：

1. What Changed 2. Who Is Affected 3. Upgrade Steps 4. Breaking Changes 5. Compatibility Notes 6. Validation After Upgrade

重点：

• 明确旧行为、新行为和兼容边界。
• 升级步骤要按顺序可执行。
• 如果无法从仓库确认迁移细节，明确标注 TODO:。

JSDoc / 代码注释

适用场景： 公开函数、类、模块、复杂逻辑、非显然约束。

推荐结构：

• 一句话说明做什么
• @param 描述输入约束或语义
• @returns 描述返回值语义
• @throws 描述可见错误条件
• 必要时补充副作用、前置条件、并发/缓存/权限约束

重点：

• 基于真实签名和实现，不要猜。
• 不要把代码逐行翻译成注释。
• 如果函数名已经足够直白，只补充名称表达不了的契约信息。

通用写作要求

• 直接：优先主动语态。
• 简洁：删除空话和重复解释。
• 专业：术语使用一致。
• 结构化：优先列表、表格、步骤和示例。
• 可验证：命令、路径、签名、字段都能在仓库里找到依据。

文档验证清单

在交付前，逐项检查。

事实准确性

• 关键结论能在代码、配置、测试或现有维护中的文档里找到依据。
• API 路径、方法、字段、状态码、默认值与实现一致。
• CLI 命令、脚本名、环境变量、配置键、导入路径真实存在。
• 没有编造未来计划、性能数字、上线状态或兼容性承诺。

示例与可执行性

• 代码示例使用真实接口、真实参数名和合理的最小上下文。
• 命令示例对应当前仓库结构，不引用不存在的目录和脚本。
• 文件路径、文档链接、章节跳转都能解析到真实位置。

结构与可读性

• 文档结构与当前类型匹配，而不是套错模板。
• 重要信息出现在前面，细节放在后面。
• 架构说明按数据流或调用流组织，而不是纯目录罗列。
• 注释和 JSDoc 解释的是契约和约束，不是逐行复述代码。

中文输出专项检查

• 已按需应用中文技术文档写作规范。
• 中英混排自然，没有空格和标点错误。
• 术语统一，没有过度翻译。
• 句子简洁，没有机翻味和欧化长句。

安全与边界

• 没有泄露密钥、令牌、私有地址、内部系统名或敏感备注。
• 没有把仅适用于内部环境的步骤包装成公开说明。
• 无法确认但必须提到的内容，已明确标注 TODO:。

文档生成工作流

步骤 1：先判断你在写什么

先把任务归类，再决定结构和语气：

1. README / 项目概览 2. API 文档 3. 架构说明 / 设计说明 4. 用户指南 / 运维指南 / FAQ 5. CONTRIBUTING / 迁移说明 / 发布说明 6. JSDoc / docstring / 代码注释

如果用户只说“补文档”，优先从目标文件路径、目录位置、已有文档名称判断；不要上来就套用统一模板。

步骤 2：从代码取证，而不是从想象出发

1. 先读现有文档，了解项目已经使用的术语和表达方式。 2. 查看目录结构、入口文件、配置文件、示例、测试和公开接口。 3. 记录关键信息：

• 启动方式
• 依赖和前置条件
• 核心流程
• 对外接口
• 失败场景或边界条件

4. 对下面这些内容必须找到代码证据：

• API 路径、参数、返回值、错误码
• CLI 命令、配置项、环境变量
• 默认值、约束、能力边界

5. 如果是注释或 JSDoc，必须先读具体实现，再写说明。

步骤 3：确定读者和语言

1. 区分读者：

• 新用户：更关注“怎么开始”
• 使用者：更关注接口、限制、错误处理
• 维护者：更关注设计决策、模块关系、变更影响

2. 语言策略：

• 代码库已有中文文档：延续中文风格
• 用户明确要求中文：使用自然中文，不要机翻
• 用户明确要求英文：保持简洁技术写作

3. 中文文档需要额外检查：

• 中英混排是否自然
• 术语是否统一
• 是否存在欧化长句和“被用来”式机翻味

步骤 4：先列提纲，再写正文

1. 从读者最关心的问题开始组织结构，不要机械地按目录树逐段解释。 2. 将内容压成几个高信息密度部分：

• 项目是什么
• 怎么开始
• 怎么使用
• 有哪些限制或注意事项
• 出问题时怎么看

3. 如果是架构文档，优先按数据流、请求流、模块协作关系组织，而不是按文件名罗列。 4. 如果是跨组件架构说明，优先加入 Mermaid 图。

步骤 5：撰写时的硬约束

1. 示例代码必须能直接对应到项目真实接口或真实命令。 2. 不要编造性能数字、默认值、错误码或未来计划。 3. 无法从仓库确认但又必须提到的信息，用 TODO: 标记。 4. 注释和 JSDoc 只写高价值信息：

• 参数约束
• 返回值语义
• 副作用
• 错误条件
• 不明显的设计意图

5. 不要写这种低价值注释：

• “设置变量值”
• “循环数组”
• “调用函数”

步骤 6：交付前自检

至少检查下面几项：

1. 结构是否符合当前文档类型。 2. 命令、路径、导入、接口签名是否真实存在。 3. 链接和文档引用是否有效。 4. 没有泄露密钥、私有地址、内部备注。 5. 中文输出是否通过中文技术写作规范的排版和语言检查。

JSDoc 示例

/**
 * Fetch orders for a specific user.
 *
 * @param userId - Unique user identifier.
 * @param options - Query options such as limit, status, and sort order.
 * @returns Orders visible to the caller after filtering and pagination.
 * @throws Error when the upstream order service is unavailable.
 */