user-manual-authoring · diff
git:20260730.6ee304a to git:20260908.6caf1bf
5 added, 5 removed. Audit A to A.
---
name: user-manual-authoring
description: 开源/公开用户站点与最终用户手册写作 Owner — guide/README/reference/migration/changelog/operations；与维护者开发站不等价；经 DocsAudienceIntent 路由。
---
# User Manual Authoring Skill
## 职责
当任务目标是**开源/公开用户使用**站点文档、最终用户手册、README、quick start、接入手册、API/CLI **reference（用户侧契约面）** 或公开能力页时，本 Skill 是优先写作入口。
主受众必须是**使用者**（含「使用库的开发者」），**不是**本仓库维护者。成功标准：理解 → 安装/接入 → **第一次成功** → 任务 → 配置 → 失败恢复。
技术方案、接口契约深页、实现计划和维护者 checklist 只能后置或拆任务；维护者开发站走 `maintainer-docs-site-authoring`。
## 触发条件
| 场景 | 是否触发 |
|------|:--------:|
| `docsAudience=public-user`（DocsAudienceIntentGate） | 必须 |
| 用户要求“用户使用文档 / 使用手册 / 最终用户文档 / 开源用户站” | 必须 |
| 用户要求 README、quick start、接入手册、官网使用说明或公开能力页 | 必须 |
| docs-first、先写文档再开发、后续按文档实现 | 必须 |
| API/CLI/Config **reference**（使用者查表） | 必须（可编排 `dev-docs` light-api） |
| 维护者开发站 / contributing / 发版 runbook / ADR 主叙事 | N/A → `maintainer-docs-site-authoring` |
| 仅「写文档站/website」且 ambiguous | N/A → **阻断消歧**，禁止开写 |
| 纯架构说明且受众为维护者 | N/A → `dev-docs` / `maintainer-docs-site-authoring` |
## 输入顺序
用户最终文档不得直接从未确认草稿生成最终承诺。推荐顺序：
1. 原始需求或材料保留为输入锚点。
2. `00-需求概况.md` 只作为整理草稿，不替代确认事实源。
3. 以 `01-需求确认.md` 或产品直接提供的 `01-产品需求.md` 作为文档事实源。
4. 判断 `documentationSurface=docs-site | README-minimum | N/A`。
5. 先产出最终用户使用文档。
6. 涉及前端、API 或外部调用方时，再生成契约文档。
7. 技术方案、实施方案、实施计划和 ECR 必须对照用户文档。
## 文档契约
| 字段 | 要求 |
|------|------|
| `primaryAudience` | 必须是用户 / 使用者；内部开发者只能是次级受众 |
| `docsSurface` | `guide` \| `readme` \| `reference` \| `migration` \| `changelog` \| `operations`（由 DocsAudienceIntent 锁定） |
| `documentLocation` | 写清是文档站、README、需求交付目录、官网页还是 maintainer-only |
| `userJourney` | 覆盖理解、安装/进入、第一次成功、常见任务、配置、失败处理和下一步 |
| `informationArchitecture` | 文档站要区分用户手册、reference、operations、compatibility、implementation、maintainer |
| `pageRoleMatrix` | 多页文档站列出页面 role、受众、sourceOfTruth、nav/sidebar 位置和用户主路径状态 |
| `sidebarSemanticModel` | 文档站列出每个 sidebar group 的用户任务模型、相邻页面职责、route/label 真相源和非归属说明 |
| `configurationModel` | 配置字段、默认值、选择建议、错误与排错必须简单易懂 |
| `realWorkflowExample` | 队列、任务、异步、导入导出、推送或批处理类文档必须给真实批量工作流 |
| `renderedFlowEvidence` | Mermaid / 流程图 / 文档站主题必须有真实渲染或运行态验证证据 |
| `semanticParityEvidence` | 行为语义、默认值、兼容路径、支持/不支持承诺必须有 `BehaviorSemanticDocsParityGate` / `NegativeTranslationParityProbe` 证据 |
| `exampleTruthEvidence` | option/config/method/callback 示例必须有 `DocsExampleTruthSurfaceGate` / `CallbackExampleScopeProbe` 证据 |
| `expertOutputQualityEvidence` | 示例、fixture、quick start 或接入手册必须有 `expert-output-quality` / `ExpertOutputQualityGate` 证据，区分生产推荐路径、框架原生能力、fixture/mock/demo 边界和反模式 |
| `developerInfoPlacement` | 开发契约、技术方案、数据模型、维护者 checklist 后置或单独标记 |
| `consumerMap` | 同步 README、website、Profile、examples、prompts、templates、validate 和部署副本 |
## 必执行门禁
> 共享 Gate 分组与 requiredEvidence 以 `../spec-governance/gate-registry.json` 为准（`user-manual` / `docs-ia-readability` / `docs-semantics-examples` / `docs-audience-render-sequence` / `scenario-durable-workflow` / `expert-output-quality`）。下表是本 Owner 的**差分清单**（触发 → 要证什么），不维护跨 Skill 百科。
| 触发 | 要证什么（摘要） |
|------|------------------|
| 任意用户手册 / README / 站点文档 | 冻结用户主受众与落点；主路径覆盖理解→第一次成功→任务→配置→失败恢复；公开面不混维护者 checklist |
| docs-first / 最终用户手册 | 文档先于技术方案成为用户路径合同；写目标版本可执行路径，不是 preview 状态说明 |
| 文档站 / 多页 README | page role / sidebar 任务模型 / IA 分区；中文主表达；主题与生成站点运行态（不仅 Markdown） |
| 队列 / 异步 / 批处理 quick start | 真实业务工作流；声称场景完整或持久化编排时追加 scenario / durable 证据（见 registry） |
| 行为承诺 / 示例 / 回调 | 语义与 public API/runtime 对齐；示例可追溯 type/schema/dispatcher；fixture 不得冒充生产推荐路径（`expert-output-quality`） |
| 能力 / 导航 / 路径变更 | 同步 README、website、Profile、examples、validate、部署副本与代码消费点 |
## 执行步骤
1. 判定文档目标：`docs-site`、`README-minimum`、`public page`、`requirement deliverable` 或 `N/A`。
2. 核对事实源：确认需求/产品需求、当前版本、发布状态和公开能力边界。
3. 写出用户主路径：这是什么、适合谁、第一次成功、常见任务、配置、排错、限制、下一步。
4. 拆分信息架构：用户手册与 API/CLI/config reference、operations、implementation、maintainer 分开。
5. 建立 `pageRoleMatrix` 与 `sidebarSemanticModel`：确认每页 role、sidebar group、相邻页面职责、route 真相源和非归属说明。
6. 对真实工作流补示例：避免只有单点 API 或单个硬编码 job。
7. 对示例 / fixture / quick start 执行 `expert-output-quality`：冻结 `roleBaseline`、`productionRecommendedPath`、`frameworkNativeCapability`、`fixtureBoundary`、`antiPatternContrast` 与 `evidenceMatrix`。
8. 建立 `consumerMap`，列出 README、website、Profile、examples、prompts、templates、validate、部署副本和代码消费点。
9. 完成后按风险调用 `audit-user-manual` 做用户侧文档聚合 review；落点为 README / 主入口文档时再叠加 `audit-readme`，通用结构与准确性由 `audit-document` 承接。
## 与其他 Skill 的关系
- `dev-docs`：识别文档任务后，**用户站/README/用户手册必须 handoff 本 Skill**；reference 可编排 light-api；纯维护者技术文或架构走 `dev-docs` / `maintainer-docs-site-authoring`。
- `maintainer-docs-site-authoring`：维护者开发站 Owner；受众正交。
- `readme-authoring`：README 是本 Skill 的 README 专项分支，继续负责 README 章节顺序与用户旅程细化。
- `audit-user-manual`：负责用户侧文档、项目文档、菜单导航和文档 IA 的聚合审查，不替代写作入口。
- `audit-readme` / `audit-document`：负责 README 专项与通用文档维度，通常由 `audit-user-manual` 编排。
- `expert-output-quality`：负责专家型产物质量，避免文档把 fixture/mock/demo 或低阶重复写法包装成生产推荐路径。
- `test-router`：选择生成站点、链接、用户路径、Browser/截图或代码级替代验证。
- `document-sync`：按 `consumerMap`（含 `audience=public-user`）检查当前消费者和部署副本。
- - `DocsAudienceIntentGate`：`scripts/lib/docs-audience-intent.js` + `npm run test:docs-audience`。
+ - `DocsAudienceIntentGate`：模型判定受众，`scripts/lib/docs-audience-intent.js` 校验结构化决策；`npm run test:docs-audience` 仅验证契约接线。
## 认知高度与任务语言（L3 · 强制）
> 受众对（public-user）不等于可读。guide/readme 不得做成「完整但全是底层函数」的符号说明书。
### 认知高度三层
| 高度 | 含义 | guide/readme 主路径 | reference |
|------|------|---------------------|-----------|
| **Task** | 用户要完成的事、场景、步骤、选择建议 | **必须为主叙事** | 可附「何时用」 |
| **Concept** | 领域概念、配置含义（白话） | 服务 Task | 可简要 |
| **Symbol** | 类型名、方法签名、内部模块 | **后置**或链到 reference | 允许密 |
### 写作硬规则
1. **唯一推荐路径**：quick start 只推广一条 `productionRecommendedPath`；底层装配标「高级/扩展」。
2. **先任务后符号**：目录与标题优先任务名（「发消息」），不是 `MessageDispatcher`。
- 3. **guide ≠ API inventory**：快速开始若以 ≥3 个未解释的函数调用链为主且无任务句 → **完成失败**。
+ 3. **用户任务为主线**：模型审查快速开始能否帮助目标读者完成第一次实际使用；不能用函数调用数量或是否出现某个任务词代替可读性判断。
4. **渐进披露**：5 分钟会用 → 30 分钟会选 → 查表 reference；禁止一篇写穿全部 public 函数当使用文档。
5. **术语**：内部名首次出现必须白话；配置先默认与选择建议再字段表。
6. **reference**：符号可密，每项至少「用途一句话 + 与推荐路径关系/何时不用」。
### 延展失败场景（写作与审查时主动对照）
用户只提一种「看不懂」时，仍应自检相邻风险（问题驱动场景延展）：
| 组 | 场景 |
|----|------|
| A 叙事 | 函数清单 guide、概念堆无任务、配置字典、错误码无恢复、多入口无推荐 |
| B IA | guide/reference 混主路径、源码侧栏、深链才到第一次成功、一篇写穿 |
| C 示例 | 不可跑、fixture 当生产、无失败路径、版本漂移 |
| D 伪用户 | 库文档按贡献者写、运维当研发、术语三套 |
| E 假完整 | TBD、超版承诺、三口径 |
| F 负担 | 前置未声明、图文不符 |
| G 元失败 | 受众对高度错、好读但假、单页好整站乱 |
### 完成前漂移自检
- 锁定 `docsAudience=public-user` 后，正文不得以 release checklist / monorepo 内部 / ADR 列表 / 内部台账为**首屏主叙事**。
- - `classifyDocsAudienceDriftSample('public-user', body)` 不得为 `drift-maintainer-on-user`。
- - **`classifyUserDocsCognitiveAltitudeSample(body, { surface })` 不得为 `function-inventory-as-guide` 或 `concept-dump-no-task`**（guide/readme/quick start）。
+ - 模型审查读者任务、叙事顺序与可读性，形成绑定正文摘要的 `DocsContentReviewV1`（kind、conclusion、rationale、evidenceRefs，受众漂移追加 audience）；适配函数只投影该结论，没有审查时为 unverified。
+ - `classifyDocsAudienceDriftSample('public-user', body, review)` 与 `classifyUserDocsCognitiveAltitudeSample(body, { surface, review })` 必须使用相应 kind 的当前审查记录；修改正文后重新审查。
- 无安装/第一次成功路径不得宣称用户站完成。
- - 验证：`npm run test:docs-audience`。
+ - 验证：模型内容审查、实际用户路径；`npm run test:docs-audience` 仅证明协议正确，不能证明某份文档可用。
## 禁止
- 禁止把用户要求的站点文档写成开发文档、技术方案、实现计划或维护报告。
- 禁止让开发契约、目标 API、Redis/缓存模型、数据模型或验收 checklist 成为用户主入口。
- 禁止把未确认的 `00-需求概况.md` 当成最终用户承诺。
- 禁止把最终用户手册写成整站全部内容容器。
- 禁止把当前不可用状态说明冒充目标版本最终用户手册。
- 禁止把 fixture、mock、demo、硬编码单例或重复 route/middleware/resource 声明写成用户主路径的生产推荐实践；必须标明验证用途和推荐替代。
- 禁止在单任务内同时写维护者站并宣称双受众完成；多受众须拆任务。
- **禁止以底层函数/类型调用链作为 quick start 的唯一主叙事**（无任务句、无推荐路径）。
## 同步锚点（validate / consumer）
FixtureBoundaryDisclosureGate · ScenarioCoverageMatrixProbe · DurableBatchOrchestrationProbe
## 额外同步锚点
ChinesePrimaryExpressionGate · SidebarPageRoleMaterializationProbe · SidebarGroupSemanticModelProbe
<!-- auto-sync anchors -->
UserFacingDeliveryChainGate · FinalUserManualFirstGate · UserPathContractSweep · UserManualProductizationGate · UserManualRenderedFlowAndRealWorkflowProbe · DocsPageRoleMatrixGate · DocsThemeRuntimeVisualProbeGate