# Documentation Authoring > 从已完成的代码框架、配置和工程资料建立、新增、补充或重构技术文档的信息架构、内容边界与表达方式。 - Skill: `hackycy/documentation-authoring` (Agent Skill, multi-file: 6 files) - Install (CLI): `npx skillmds@latest add hackycy/documentation-authoring` - Raw SKILL.md: https://api.skillmd.com/api/skills/hackycy/documentation-authoring/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Docs & Writing - Author: hackycy (https://skillmd.com/u/hackycy) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/hackycy/documentation-authoring --- # Technical Documentation Authoring 把技术文档编译成稳定、可维护、容易导航的知识载体。先决定事实属于哪里和读者需要什么，再组织内容，最后润色表达。 ## Core principles - 写入前先识别信息类型；不要把发现过程直接变成文章结构。 - 每个持久事实只有一个 canonical owner；owner 可以是源码、配置、schema、生成器、文档或决策记录。 - 根据 reader intent 选择文档类型，而不是根据文件名或已有材料选择。 - 动笔前建立 Document Contract：读者、目标、主题、范围、排除项、权威来源和细节上限。 - 文档类型不能扩大 scope；上层文档概括直接子级并链接到细节 owner。 - 按前置条件、依赖和可验证结果组织内容，不按调查、实现或提交顺序组织。 - 将当前状态、设计理由和历史叙事放入不同的文档职责中。 - 跨边界时链接权威细节，只保留符合当前范围且足够稳定的内容。 - 先由主代理冻结 authoring plan，再决定是否派发；子代理只执行边界清晰的局部写作。 ## Working contract 执行写作、重写、拆分、合并或结构审查前，先形成一个简短的 Document Contract。可以在内部完成；只有任务需要对齐时才把它写成可见工件。 记录以下字段： - **Reader intent**：读者要学习、完成任务、查询、理解、追溯还是遵守规则。 - **Document type**：与 intent 匹配的主要文档类型；一个文档只保留一个主要 intent。 - **Subject**：文档直接负责的主题或系统层级。 - **Scope**：包含的对象、行为和深度。 - **Exclusions**：明确留给其他文档或权威来源的内容。 - **Authorities**：支持当前事实的源码、配置、生成文件、决策记录或已有文档。 - **Detail ceiling**：在当前主题和读者目标下允许的最高细节层级。 若无法确定 owner、reader intent、scope 或权威来源，先保留不确定性并报告缺口；不要凭经验补写产品决定或当前行为。 ## Authoring workflow ### 1. 定位任务和文档位置 识别这是新建、更新、拆分、合并还是结构审查。读取适用的 `AGENTS.md`、`CLAUDE.md`、`CONTEXT.md`、文档索引和相邻文档，确认仓库已有的层级、命名和链接约定。 如果目标文档不存在，将任务视为 greenfield documentation：从代码目录、公共 API、配置 schema、测试、示例、命令和生成文件建立候选文档地图。先判断需要一篇入口文档还是一组按 owner 和 reader intent 划分的文档，不要把整个代码框架直接压缩成一篇大而全的说明。 完成条件：已有文档时，已经知道目标路径、上级文档、直接子级和适用的本地规则；没有已有文档时，已经知道代码框架的主要边界、候选文档集合、每篇文档的初步 owner 和权威来源。 ### 2. 盘点并分类信息 列出准备保留的事实、解释、步骤、示例、限制和历史材料。按信息类型分类，并区分当前状态、持久理由、操作过程、查询资料、规则、事故和生成内容。 需要详细分类表时，读取 [`references/information-and-ownership.md`](references/information-and-ownership.md)。 完成条件：每一块候选内容都有信息类型；没有把不同类型的材料混成一个未定义的段落。 ### 3. 路由事实到 canonical owner 为每个持久事实查找现有 owner。优先使用源码、配置、schema、生成器和现有决策记录作为权威来源；文档只拥有它职责范围内的解释、流程或稳定契约。 已有 owner 的内容只保留必要摘要和指向 owner 的链接。发现多个冲突 owner 时，先报告冲突并记录需要解决的权威性问题。 完成条件：每个非平凡事实有且只有一个 owner；当前文档没有复制别处的权威细节。 ### 4. 根据 reader intent 选择文档类型 从读者目标选择 Tutorial、How-to、Reference、Explanation、ADR、Policy 或 Postmortem 等类型。不要因为一个文件同时包含多种内容就给它叠加多个主要类型；当混合意图达到影响导航或维护的程度时拆分文档。 读取 [`references/document-types-and-composition.md`](references/document-types-and-composition.md) 获取类型选择和结构模式。 完成条件：能用一句话说明“谁为了什么读这篇文档”，并能指出一个主要文档类型。 ### 5. 固定 scope 和 detail ceiling 写出主题、受众、目标、包含项、排除项、权威来源和细节上限。将文档限制在自己的主题、所在层级和直接子级职责内；把更低层级的机制、测试、清单和实现细节移到 owner。 文档类型不能扩大 scope。父文档描述组成、责任和高层行为；子文档拥有类型定义、参数、测试机制或具体操作。 完成条件：每个章节都能回答“它如何服务当前读者目标和 scope”；超出边界的材料已有去处或链接。 ### 6. 形成可执行的 authoring plan 先安排读者必须知道的前置概念，再安排依赖它们的操作、解释或查询内容。按照文档类型使用对应结构，不把调查、实现、讨论或提交顺序当成教学顺序。 为大文档记录章节树、事实 owner、章节依赖、目标文件、排除项和每个章节的验收条件。计划必须能让另一个代理在不重新设计全局结构的情况下完成一个局部任务。 完成条件：读者不需要跳到后文才能理解前文的必要术语、前置条件或动作；每个主要段落都服务一个明确问题；每个计划单元都有唯一范围和完成条件。 ### 7. 选择执行模式并派发 默认采用单代理路径。只有同时满足以下条件时才开启子代理： - 计划已经冻结，reader intent、document type、scope、owner 和主要结构没有未解决冲突。 - 至少存在两个可以独立读取、独立编写、独立验收的工作单元。 - 每个工作单元有唯一目标文件或章节 owner，任务之间不会并发编辑同一段正文。 - 依赖关系已显式记录；需要共享的事实已有权威来源，而不是依赖子代理互相猜测。 - 分派和合并的成本低于主代理持续承载全部文档上下文的成本。 满足条件时，读取 [`references/orchestration-and-delegation.md`](references/orchestration-and-delegation.md)，由主代理生成派发简报并调用子代理。主代理保留全局计划、事实归属、跨章节链接、合并决策和最终验收权。子代理不重新设计文档类型，不修改其他工作单元，也不把未证实的事实写成结论。 不满足条件时，主代理继续单独完成写作。单文件局部补充、少量段落修订、单一 owner 的 Reference 更新和强串行依赖都属于单代理路径。 完成条件：已经明确选择 single-agent 或 delegated execution；若派发，所有任务都有边界、依赖、输出格式和验收条件。 ### 8. 直接写当前契约和可观察行为 用具体主体、动作、API、选项和结果表达内容。先写当前状态和读者可观察的行为，再补充默认值、限制、例外、原理和取舍。明确区分“必须”“默认”“推荐”和“可以”。 Tutorial 和 How-to 可以以最小示例为解释中心；Reference 以可检索的定义和边界为中心；ADR 和 Postmortem 保留各自需要的理由或时间线。 需要完整表达规则和校验表时，读取 [`references/writing-and-validation.md`](references/writing-and-validation.md)。 完成条件：正文陈述的是可维护的事实、契约或步骤，而不是推理过程、实现流水账或空泛的元话语；派发任务的输出都已回收到主代理。 ### 9. 合并并统一 若使用子代理，主代理逐项检查每个输出是否符合 authoring plan。解决重复事实、术语漂移、章节边界、交叉链接和风格不一致；将未解决的问题集中记录，不让局部代理自行发明全局决定。不要把子代理的过程说明直接并入正文，只合并可维护的结果。 完成条件：每个派发单元都有结果或明确阻塞原因；同一事实没有多个 owner；全局目录、链接、术语和读者路径一致。 ### 10. 链接、收缩并校验 删除重复事实、手抄清单、无关背景和超出 detail ceiling 的细节。用能说明目标的链接连接 owner、子文档、源码和决策记录。按照参考文件中的顺序完成结构性和语言性校验。 完成条件：owner、类型、scope、依赖顺序、当前/历史边界、链接和表达规则都已检查；没有遗留未处理的冲突或不确定性。 ## Boundaries 不要把仓库专属的文件层级、脚本命令、字数预算、代码块编译规则、双语流程或特定术语写成通用规则。读取本地项目约定并服从它们；本 Skill 只提供跨项目稳定的文档决策框架。 不要把 `README`、`architecture.md` 或 `AGENTS.md` 当成固定的通用文档类型。先判断 reader intent，再遵循项目对这些载体的具体约定。 ## Final handoff 完成后简要说明：文档类型和 reader intent、canonical owner 的处理、scope 边界、涉及的链接或拆分，以及仍需人工决定的事实冲突。不要把未解决的问题伪装成当前状态。