技术文档工程

• 理解 Docs-as-Code 的理念（文档当代码对待）
• 掌握同仓、同 PR、同 CI 的具体工作流
• 理解文档质量门禁与发布流程

Docs-as-Code 的核心是把文档当作一等公民的代码来管理：文档用 Markdown 等纯文本格式，存于 git 仓库，与代码一起走版本控制、评审、CI 与发布。工作流设计：同仓——文档与代码放在同一仓库（或子目录），保证文档与代码版本一致；同 PR——文档变更与相关代码变更在同一 PR 中提交并一起评审，避免"代码改了文档没改"；同 CI——文档也经过 lint（如 markdownlint、vale）、死链检查、可运行示例验证，只有通过才允许合并；发布——文档在 CI 中构建并发布到文档站点，与代码版本绑定。这套流程让文档的更新成为开发流程的一部分，而非额外的"事后任务"。

Docs-as-Code 的本质是"用工程化的手段管理文档"：版本控制解决文档与代码的版本对齐，评审保证质量，CI 承载自动化检查，发布保证可访问。它把文档从"静态资产"变成"随代码演进的活文档"。

• 理解 Diátaxis 四象限的划分逻辑
• 掌握每类文档的写作目标、读者与结构
• 避免四类文档的混淆

Diátaxis 按"任务导向 vs 理解导向"和"学习者 vs 使用者"两个维度划分四类文档。Tutorial（教程）：面向零基础学习者，目标是"通过一系列步骤获得成功体验"，结构是循序渐进、有明确终点、每步可验证，读者应能从头到尾完成；How-to Guide（操作指南）：面向有目标的使用者，目标是"解决一个具体问题"，结构是"针对某任务的分步操作"，关注可行性而非原理；Reference（参考）：面向查证的使用者，目标是"准确、完整地描述事实"，结构是索引化、条目化（如 API 文档、命令参考），只描述"是什么"不解释"为什么"；Explanation（解释/概念）：面向想理解的使用者，目标是"阐释概念与背景、为什么这样设计"，结构是论述式、有上下文，可谈权衡与取舍。四类文档互补，写作时应明确类别，避免"How-to 里写原理、Reference 里写步骤"的混用。

Diátaxis 的价值在于把"文档混乱"拆解为四类职责清晰的结构，让作者知道"该写什么、怎么写"，让读者知道"该去哪找"。四类文档对应不同的阅读心智，混用会同时损害清晰度与可检索性。

• 理解自动化生成 API 文档的优势与局限
• 掌握人工补充的字段与时机
• 保障 API 文档质量的工程手段

基于 OpenAPI/Swagger 的 API 文档自动化生成能保证"契约与文档一致"（从代码注解或规范生成），避免手写文档与实现漂移。但自动生成的文档往往只有方法名、参数、返回类型等机械信息，缺少业务语义。因此需人工补充：每个接口的"用途说明"（Description）、参数与字段的语义、示例请求/响应、错误码含义、使用注意事项与边界条件。保障质量的工程手段：把 OpenAPI 规范纳入版本控制与 CI，校验规范合法性（如 openapi-validate）、检查 description 是否缺失、跟踪示例是否与 schema 一致；将生成文档发布到文档站点并做页面渲染测试；对破坏性变更（删除字段、改参数）在 CI 中提示。核心是"自动化保一致、人工补语义、CI 守质量"。

纯自动生成的文档"准但不全"，纯手写的文档"全但不准"。最佳实践是以 OpenAPI 为契约源自动生成骨架，再用人工补充语义与示例，并用 CI 校验保证规范与实现的同步。质量保障的关键是"契约驱动 + 人工增强 + 自动校验"三者结合。

• 理解单一来源（Single Source of Truth）原则
• 掌握引用、include、自动生成三种手段
• 消除文档漂移

单一来源原则指"同一事实只在一处权威定义，其余地方引用它"。消除重复的手段：引用（Reference）——在文档中通过链接引用权威定义，而不是复制内容；include（包含指令）——文档构建工具支持把共用片段（如版权、配置示例、通用说明）从单一文件 include 到多处，改变源文件即可全局更新；自动生成——从代码、OpenAPI 规范、配置等真实来源自动生成文档内容，避免手工维护造成漂移。实施时，先识别"重复出现的权威信息"（如版本号、API 契约、安装命令），将其收敛到单一源文件，再让其他文档通过 include 或引用获取。这样修改一处，全局一致，从根本上消除漂移。

文档漂移的根源是"多处手工维护同一事实"。单一来源通过"定义一次 + 处处引用"把事实管理收敛到一处，配合 include 与自动生成，让一致性由构建过程保证而非靠人自觉。这是对抗文档腐朽的核心策略。

• 理解文档漂移检测的方法
• 掌握 CI 中的文档检查项
• 建立文档质量门禁

检测文档与代码漂移的方法：将文档与代码同仓管理，通过 PR 关联迫使文档随代码更新；用链接检查工具（如 markdown-link-check）检测死链；用结构/lint 工具（markdownlint、vale）检查格式与措辞；对代码示例做"可运行性验证"——在 CI 中把文档中的示例代码提取出来编译/执行（如用 runner 或 doctest 工具），确保示例真实可用；对截图做时间戳或人工定期复核，避免过时界面。结合 CI 门禁：文档变更必须通过上述检查才能合并，并在发布前渲染预览。持续维护的核心是"把文档检查自动化并纳入 CI，让文档质量成为开发流程的硬约束"。

漂移检测依赖"文档即代码"的工程化：链接、格式、示例、与代码的对应关系都能用自动化工具检查。死链与不可运行示例是文档腐化的两大信号，CI 门禁能系统性遏制。截图因无法自动校验，需人工定期复核。

• 理解信息架构（IA）的设计原则
• 掌握导航、索引、搜索的组织方式
• 降低新人检索成本

设计文档信息架构应从"用户任务"出发而非"作者视角"：按读者角色（开发者、运维、新人）与任务类型（入门、操作、查参、理解）组织内容，而非按部门或文件所有权。具体手段：建立清晰的导航层级（分类不过深、避免碎片化）；提供多入口——目录、标签、全文搜索、FAQ；为文档建立一致命名与路径规范；用"文档索引/地图"（如一个 README 站点首页）汇总各类文档入口；为高频问题建立快捷入口。信息架构的目标是让新人"三步内找到目标"，可通过用户测试（如让新人找某类信息并计时）验证并迭代。搜索友好则依赖规范化标题、关键词、元数据与全文索引。

新人找文档靠的是"心智模型"而非目录记忆。以角色和任务组织信息架构、配合多入口与强搜索，能显著降低检索成本。信息架构是"如何组织文档"的决策，直接影响文档的可用性。

• 理解多语言文档的维护模式
• 识别漂移根源与同步机制
• 选择适合的翻译工作流

多语言文档的漂移源于"源文档更新后翻译未同步"。控制手段：单一来源原则——源语言文档是唯一权威，翻译版本是派生；建立"同步门禁"——源文档变更时标记翻译版本"过期"，在 CI 或文档系统中提示需更新；用翻译记忆（Translation Memory）与机器翻译（如 LLM 辅助）降低翻译成本，但必须人工审核；用规范化流程（如"先改源、再译、一次发布"）保证版本对齐；对翻译质量做抽查与评审。选择上，小团队可用"改源后手动标记并集中翻译"，大项目可引入翻译管理平台（TMS）自动追踪待翻译条目。目标是让"翻译过期"可被显式标记出来，从而避免无声的漂移。

翻译漂移的根因是"多份副本各自演进"。单一来源 + 过期标记 + 同步机制，让每份翻译都明确"我所对应的源版本"，保证翻译与源版本可对齐。自动化翻译降低门槛，但质量保障仍需人工环节。

• 理解文档"活"的核心理念（与代码同步演进）
• 掌握文档与代码的关联方式
• 设计过期文档的自动检测

让文档"活"起来的关键是让文档与代码形成强关联：文档与代码同仓、随代码 PR 更新；在文档中引用代码符号、配置、API 契约，从代码自动生成数据或接口部分；通过脚本校验文档中引用的代码标识是否仍然存在。过期检测机制：对文档设置"最后核验日期"（last-reviewed），超期未核验则在文档中标记或 CI 提醒；通过构建时间戳、链接检查、示例运行检查发现失效内容；对"是否仍被引用"做统计，识别孤儿文档。核心是建立"文档随代码演进 + 自动过期提醒"的双重机制，让维护者与读者都能感知文档新旧状态。

文档僵化的根源是"与代码脱节"。强关联（同仓、引用代码、自动生成）让文档随代码更新，过期检测（核验日期、链接与示例检查）让失效文档被显式暴露。二者结合让文档持续保鲜。

• 理解不同文档类型的读者定位
• 明确维护责任归属
• 建立文档所有权机制

读者与责任划分：API 文档的读者是使用该 API 的外部/内部开发者，责任应归 API 的维护团队（接口设计与实现者），因为他们掌握接口语义，通常由 OpenAPI 规范驱动生成并维护；架构文档的读者是架构师、开发者与新人，责任归架构师或技术负责人（架构决策者），它们需与 ADR、技术选型保持一致；运维文档（部署、监控、故障排查）的读者是运维/DevOps 与值班工程师，责任归运维团队或 SRE，与基础设施、SRE 流程绑定。划分原则是"谁最了解、谁受影响、谁负责"，并建立"文档所有者（Owner）"机制，每个文档有明确负责人与评审流程，避免"文档无人维护"。

文档责任归属是"文档所有权"管理的核心。三类文档读者与生产方不同，责任应随内容的生产方与消费方匹配。设立 Owner 与评审机制，确保每类文档有人负责、有人核实，避免"公共地带"无人维护。

• 理解文档分层（用户/API/内部）的逻辑
• 掌握各层的内容与读者
• 避免各层混淆

文档按"读者距离"分层：用户文档面对最终用户（非技术），内容是产品使用、功能说明、常见问题，语言通俗、面向任务；API 文档面对集成开发者，内容是接口契约、参数、示例、错误码，以规范生成 + 人工补充；内部文档面对团队内部，内容是架构设计、运营流程、代码约定、决策记录，读者是工程师与运维。分层原则是"给对应读者只呈现该层内容"：用户不该看到内部实现细节，开发者不该被产品教程干扰。各层维护责任与发布渠道也不同（用户文档面向公网、API 文档面向开发者门户、内部文档仅在组织内）。分层让文档结构清晰，读者能快速定位到自己需要的层次。

文档分层对应"读者与使用场景"的差异。用户/API/内部三类文档的读者、内容、渠道、维护责任各不相同，分层既避免信息混杂，也便于各层独立优化。这与 Diátaxis 按任务划分是互补的视角。

• 理解文档版本化（随代码版本发布）
• 掌握历史版本浏览与"最新"导航
• 设计主版本分支策略

文档版本化设计：将文档与代码同仓，按代码版本打标签（tag），文档随对应版本的代码一起发布，保证"某版本文档描述该版本代码"；文档站点支持在版本间切换（如 Docusaurus 的 versioned docs、VitePress 的版本功能），提供历史版本浏览；"最新"（latest）导航指向当前稳定版（或 active 分支），并明确标注"当前版本"与"历史版本"。主版本分支策略：对仍受支持的 main 分支维护"最新"文档，对发布的历史版本（如 v1.x、v2.x）保留独立版本目录，读者可切换版本查看对应文档。同时要处理"版本过期"——对不再维护的版本文档标注 EOL（End of Life）提示。目标是让用户既能看最新、也能查历史，且两者与实际代码版本严格对应。

文档版本化的意义是"文档与代码版本对齐"，避免"文档描述的是旧版而代码是新版"。通过版本标签 + 文档站点版本切换 + "最新"导航，满足最新查阅与历史追溯两种需求。versioned docs 的变更是"新增版本"而非"覆盖旧版"，保持历史可查。

• 理解文档质量的度量维度
• 掌握定性与定量指标
• 建立文档改进闭环

文档质量可从多维度度量：满意度——通过文档页面的点赞/踩点反馈、用户问卷、NPS 评估阅读体验；效率——通过支持工单减少率、FAQ 接入率、文档解决率（用户是否因文档而免去提问）评估；行为——通过搜索点击率、页面停留时间、跳出率、文档到代码/下载的转化评估；维护质量——通过死链率、过时文档比例、示例可运行率评估。综合运用：把用户反馈（评论、投票）作为主观信号，把工单量与文档命中率作为客观信号，形成"发现问题 → 改进 → 再测量"的闭环。注意：工单减少受多因素影响，需结合归因分析，避免把改进全归因于文档。

文档度量应"主观 + 客观"结合：满意度与理解度是主观的，工单率、命中率、死链率是客观的。单一指标会失真（如工单下降可能源于功能变好），需多指标交叉验证，并建立反馈闭环持续改进。

• 理解 LLM 生成文档的优势与风险
• 掌握可用性保障与人工审核
• 建立人机协同的文档流程

LLM 生成文档可显著提升初稿效率（从代码/接口自动生成说明、示例、FAQ），但存在幻觉、过时、与实现不符的风险，因此可用性需靠"人工审核 + 事实约束"保障。实践：用 LLM 生成初稿，但以真实来源（代码、OpenAPI 规范、运行日志）为约束，生成后要求 LLM 标注不确定处；人工审核必须验证"技术事实是否准确"（参数、行为、示例可运行），而非只看文笔；对涉及安全、契约、限制的文档，审核更严格。流程设计：生成 → 智能体自检（跑示例、核对 API）→ 人工 review（对照代码）→ 合入 CI 校验 → 发布。核心原则是"AI 负责起草与效率，人负责准确性与最终把关"。

LLM 文档的可用性风险主要在"事实性"而非"流畅性"。用代码/契约作为事实来源约束生成，配合人工对照代码审核与 CI 验证，才能既享受效率又保证准确。AI 是加速器而非替代人工审核。

• 理解 Docs-as-Code 流水线的构成
• 掌握质量门禁与发布节奏
• 实现文档的持续交付

Docs-as-Code 流水线将文档作为代码交付：开发在本地用 Markdown 编辑 → 提交 PR → CI 触发文档检查（lint、死链、拼写、示例运行、构建静态站点）→ 检查通过后评审合入 → CI 自动构建并发布到文档站点（如 Vercel、GitHub Pages、自有 CDN）。质量由 CI 门禁保障（不合格不发布），发布节奏由合入触发（随代码发布或以固定频率发布），并可设置预览环境让评审者在合并前查看渲染效果。这样文档实现"小步快跑、持续发布"，任何变更都能快速上线并保持质量稳定。流水线还支持版本化发布与回滚，保证发布可控。

Docs-as-Code 流水线的核心是"自动化门禁 + 持续交付"。质量靠 CI 检查而非人工把关，发布靠合入触发而非周期性手工发布，这让文档既敏捷又稳定。预览环境让评审者在合并前验证渲染效果，降低风险。

• 理解文档自动化的手段
• 掌握同步机制
• 减少人工维护负担

文档自动化维护的关键是"从真实来源生成，减少手工副本"。手段：API 文档从 OpenAPI/代码注解自动生成；配置项、命令行参数、环境变量从代码或配置 schema 自动生成；数据模型从代码定义生成；变更日志（CHANGELOG）从提交记录或 PR 自动汇总；通过 CI 在代码变更后自动重新生成文档并检查差异。同步机制：文档与代码同仓，代码变更 PR 携带文档更新；用脚本校验"文档中的示例/接口是否与代码一致"；对无法自动生成的叙述性内容，用"最后核验日期"驱动人工复核。目标是让"自动能覆盖的交给自动化，人工只负责需要判断的内容"。

人工维护文档是漂移的主要来源。自动化生成把"文档与代码一致"从"人保证"变成"工具保证"，人工只负责需要判断与语义的内容。同步的核心是"生成 → 校验 → 更新"的持续循环。

• 理解清晰、准确、可搜索的含义
• 掌握各自的质量保障手段
• 建立文档质量基线

三个维度分别对应：清晰——读者能快速理解意图，靠精简的句子、明确的结构、术语一致、避免歧义与过度堆砌；准确——内容与事实（代码、行为、版本）一致，靠从真实来源生成、示例可运行验证、定期核验与评审；可搜索——读者能快速检索到目标，靠规范化标题、关键词、元数据、索引与合理的信息架构。保障手段：用 markdownlint、vale 等 lint 工具检查措辞与风格；用链接检查与示例运行保证准确；用一致的标题与标签体系提升搜索命中；定期评审与用户反馈闭环持续改进。三者是递进关系：先准确（不误导），再清晰（易理解），再可搜索（易找到）。

文档质量的三个维度缺一不可，且相互支撑：准确是底线，清晰提升体验，可搜索降低检索成本。用 lint、链接检查、示例验证、索引体系等工程手段，把三个维度从"靠自觉"变成"可检查"。

• 理解文档评审与代码评审的差异
• 掌握 Docs-as-Code 的协作机制
• 保障多人协作的文档质量

文档评审与代码评审的差异：代码评审侧重正确性、可测试性与可维护性，评审者通常是有代码经验的技术人员；文档评审侧重准确性、清晰度、面向读者是否恰当，评审者还应包括读者代表（如文档使用者、产品、新人），且评审标准较难统一（文笔是主观的）。Docs-as-Code 保证多人协作质量的手段：文档与代码同 PR 评审，让文档变更与代码变更一起被审视；用 lint/拼写/术语表（vale）等自动化检查作为客观门禁，弥补主观评审的不足；用模板与写在"文档规范"统一风格；用预览环境让评审者直观看到渲染效果；明确文档 Owner 与评审角色。协作上，文档评审应"小而频繁"而非"大而全"，降低评审负担。

文档评审的难点在于"主观性强、标准不一"，因此需用自动化 lint 与术语表作为客观基线，用读者代表补充主观视角，用 Docs-as-Code 的同 PR 流程保证文档与代码一起被持续评审。协作质量靠"工具门禁 + 规范模板 + 明确 Owner"共同保障。

• 理解 Markdown 作为文档格式的优势
• 掌握 lint 与 CI 在文档中的作用
• 构建文档质量流水线

三者构成 Docs-as-Code 的基础设施：Markdown 作为文档格式，纯文本、可版本控制、易 diff 与审核，是"文档即代码"的载体；lint（如 markdownlint、vale、markdown-link-check）提供客观质量检查——格式规范、拼写术语、死链、代码块格式，把主观的文档质量变成可自动校验的规则；CI 把 lint 与构建、发布串成流水线——代码变更触发文档检查、失败即阻断合并、通过后构建并发布静态站点。配合关系：Markdown 保证"可工程化"，lint 保证"质量可检查"，CI 保证"流程自动化"。三者结合使文档像代码一样被版本管理、被评审、被持续发布。

Markdown 是 Docs-as-Code 的存储与格式基础，lint 是质量门禁的客观化，CI 是流程自动化与强约束。三者缺一不可，共同把文档从"静态文件"升级为"随代码演进、可校验、能持续交付的资产"。

• 理解文档贡献的阻力
• 掌握降低门槛、提供激励的手段
• 建立文档贡献文化

降低工程师写文档的阻力是提升参与度的关键：提供模板与示例——让工程师套用成熟结构而非从零开始，降低启动成本；提供低门槛评审——简化文档评审流程，减少"写文档被反复大改"的挫败感，鼓励先合入再迭代；把文档与代码 PR 绑定，让文档成为开发流程的一部分而非额外负担；认可贡献——在评审、发布、新人 onboarding 中体现文档价值，设立文档贡献者榜或让文档维护者获得认可。同时用"文档规范"提供明确指导，减少不确定性。核心是"让写文档变简单、变有回报"，而非靠强制要求。

工程师不写文档往往因"起步成本高、无即时回报"。模板与示例降低认知成本，低门槛评审降低心理成本，PR 绑定让文档融入既有流程，认可机制提供激励。多元手段共同把文档从"额外任务"变成"低阻力、有回报"的日常行为。