深度专题四十九 FDE 的写作与文档能力

49.1 为什么写作是 FDE 的核心能力

在大多数工程师的直觉里，"硬核能力"是写代码、调模型、压性能。但对 FDE（前沿部署工程师）而言，写作与文档能力是与编码同等——甚至在某些阶段更高——的核心能力。这不是修辞，而是由 FDE 的工作场景决定的。

FDE 的典型工作链条是：进入陌生客户现场 → 快速理解业务 → 把模糊痛点翻译成可执行方案 → 现场交付 → 把成果移交客户自运转。在这条链条上，几乎每一个节点的核心产出物都是文档，而不是代码。具体看四个场景：

第一，沟通靠文档。FDE 面对的读者极为异质：客户的 CXO 关心 ROI 和风险，业务部门关心流程是否被改变，IT 部门关心集成与运维，一线员工关心会不会被替代。一个 FDE 不可能把同一套说辞讲给所有人听。口头沟通一次只能覆盖几个人，且无法留痕；只有写成针对不同读者的文档，才能让信息在客户组织内部自传播。Palantir 的 FDE 传统里，"让客户内部某个人能把你的方案复述给他的老板"是项目能否存续的关键，而这几乎只可能通过一份写得好的方案文档实现。

第二，留痕靠文档。客户项目周期通常以月或年计，人员会变动——客户方的对接人调岗、FDE 自己轮换、供应商更换。如果没有可追溯的文档，三个月后没人能说清"为什么当时选了 A 不选 B""这个参数为什么是 0.7"。这类知识缺口轻则返工，重则在出问题时互相甩锅。FDE 的职业声誉很大程度上建立在"我经手的项目都有据可查"上。

第三，转移靠文档。FDE 的终极目标不是自己长期驻场，而是把系统能力和操作知识转移给客户，让客户自运转。这个转移过程的载体就是交付文档、运维手册、培训材料。一份连客户 IT 都看不懂的运维手册，等于把项目判了死刑——上线三个月后没人会重启服务、没人会换密钥、没人会处理告警。

第四，复用靠文档。FDE 跨行业、跨客户作业，今天做制造、明天做零售。每个行业的方法论沉淀、坑位记录、模板复用，都依赖文档。一个成熟的 FDE 个人知识库，往往就是几十份结构化的勘探报告、方案模板、ADR（架构决策记录）和案例笔记。这些文档是 FDE 个人资本的复利来源。

一句话：FDE 的代码决定项目能不能跑起来，FDE 的文档决定项目能不能活下去、能不能被复用、能不能在 FDE 离开后继续产生价值。

49.2 FDE 必备的九类文档

下表是 FDE 全流程交付中高频出现的九类文档，对应 CDEF 方法论的不同阶段。每一类都有明确的读者、产出时机和核心字段，下一节给出模板。

49.3 各类文档的模板与要点

49.3.1 勘探报告（Discovery Report）

勘探报告是 FDE 进场后的第一份正式产出，决定后续方案方向。它的核心任务不是"记录客户说了什么"，而是"结构化地呈现客户现状、痛点、约束，并给出可落地的切入点"。

模板骨架：

# [客户名] [业务域] AI 落地勘探报告
编号：DR-2026-018  版本：v1.0  日期：2026-06-15  作者：[FDE 姓名]

## 1. 勘探背景与范围
- 客户委托来源、本次勘探的业务域边界、不在范围内的事项

## 2. 客户现状（事实层）
- 组织结构（对接的关键角色及其 KPI）
- 现有系统与数据资产（系统清单、数据量、数据质量初判）
- 现有流程（用流程图或时间线呈现关键业务流）

## 3. 痛点清单（按优先级）
| 编号 | 痛点描述 | 影响范围 | 量化损失（若有） | 业务方原话 |

## 4. 约束条件
- 预算 / 时间 / 合规（数据出境、行业监管）/ 组织政治

## 5. 切入点建议
- 推荐 1–3 个 PoC 方向，每个给出：预期效果、技术可行性、数据就绪度、风险

## 6. 下一步动作
- 明确的 next steps，含负责人与截止日期

## 附录：访谈记录索引、数据样本说明

要点： 第 2 节必须用事实，不用形容词；第 3 节每条痛点要能追溯到一次访谈或一份数据；第 5 节的切入点必须可执行，不能停在"建议进一步研究"。

49.3.2 方案设计书（Solution Design）

方案设计书是 PoC 或正式项目启动前的核心文档，读者跨度最大。好的方案设计书通常拆成"执行摘要 + 技术详述"两部分，让 CXO 只读前两页就能决策。

模板骨架：

# [客户名] [项目名] 方案设计书
编号：SD-2026-018  版本：v2.1  关联勘探报告：DR-2026-018

## 执行摘要（给 CXO，≤2 页）
- 业务目标（一句话）
- 预期收益（量化，如"客服首响时间下降 40%"）
- 总投入（人月 / 许可 / 硬件）
- 主要风险与应对

## 1. 业务背景与目标
## 2. 总体架构（含架构图）
## 3. 功能模块分解
## 4. 数据流与数据治理
## 5. 技术选型与理由（引用对应 ADR）
## 6. 部署与集成方案
## 7. 安全与合规
## 8. 里程碑与验收标准
## 9. 风险登记（引用 RSK 编号）
## 附录：接口契约、数据字典、术语表

49.3.3 架构决策记录（ADR）

ADR 是 FDE 工具箱里性价比最高的一种文档。它不写"系统是什么样的"，只写"为什么我们做了一个决策"。Michael Nygard 提出的 ADR 格式已被广泛采用，FDE 应在每个关键决策点（选模型、选数据库、选集成方式、定阈值）写一条。

模板（轻量版）：

# ADR-014：选型向量数据库选用 Milvus 而非 Pinecone

状态：已接受  日期：2026-06-10  决策者：[FDE]、[客户架构师]

## 背景
本项目需要在客户私有化环境部署 RAG 系统，数据不可出内网。

## 决策
选用 Milvus 2.4 自建集群，3 节点，HNSW 索引。

## 理由
1. 私有化硬约束排除 SaaS 类（Pinecone、Weaviate Cloud）；
2. 客户已有 Kubernetes 运维能力，Milvus 部署成本低；
3. 性能基准测试（附录）显示在 1000 万向量规模下 p95 延迟 23ms，满足业务。

## 后果
- 需自维集群，运维成本增加约 0.3 人月/月；
- 牺牲了 Pinecone 的托管扩容能力；
- 未来若上公有云可重新评估。

ADR 的价值在于：三个月后有人问"为什么不用 Pinecone"，不用翻聊天记录，直接指向 ADR-014。

49.3.4 周报（Weekly Status）

周报是 FDE 与客户项目经理之间最高频的契约。差的周报是流水账，好的周报让客户在任何一周都知道"项目是否健康、风险在哪、我需要做什么"。

模板：

# [项目名] 周报 W24（2026-06-09 至 06-15）

## 本周进度（对照里程碑）
- [完成] 数据接入联调，进度 100%（计划 100%，绿）
- [进行] 模型微调，进度 60%（计划 70%，黄，延后 2 天，原因：标注返工）

## 下周计划
- 完成微调并跑离线评测
- 启动灰度环境部署

## 风险与求助
- RSK-007：客户标注团队人手不足，可能影响下周灰度，需 [客户项目经理] 协调 2 人支援

## 关键决策
- DEC-022：本周确定评测指标采用 F1 + 业务方人工抽检双轨

要点：进度必须对照计划，不能只说"做了什么"；风险必须带求助对象，不能只列问题。

49.3.5 交付文档（Delivery Doc）

交付文档是验收的依据。它要回答"交付了什么、怎么验收、怎么接收"。

骨架： 交付物清单（代码仓库与版本号、模型权重与哈希、配置文件、数据集）→ 部署与验收步骤（可复制粘贴的命令）→ 验收标准（量化指标 + 通过线）→ 接收签字栏。

49.3.6 运维手册（Runbook）

运维手册是项目能不能活过三个月的关键。它不是系统说明书，而是"出问题时照着做就能恢复"的剧本。

Runbook 条目模板：

## 告警：向量检索延迟 p95 > 200ms 持续 5 分钟

影响：RAG 召回变慢，用户体验下降。
诊断步骤：
1. 登录 Grafana 看板 RAG-001，确认是否单节点 CPU 飙高；
2. 执行 `kubectl get pods -n milvus` 检查 pod 状态；
3. 若 pod 重启次数 >3，进入恢复步骤 R-03。

恢复步骤：
- R-01：扩容查询节点 `kubectl scale ...`
- R-02：重建索引（附录脚本）
- R-03：回滚到上一版本模型（附录回滚流程）

升级路径：若 30 分钟未恢复，通知 [值班 FDE] + [客户运维负责人]。

每条 Runbook 都应在演练中被实际执行过一次，否则就是纸上谈兵。

49.3.7 培训材料

培训材料的读者是一线员工，他们的特征是：没时间、怕出错、关心自己的利益。所以培训材料要做到"图多字少、操作可照抄、明确告诉他这对他有什么好处"。一份好的培训手册开头不应是"系统架构介绍"，而应是"你每天能省 40 分钟，方法如下"。

49.3.8 案例沉淀（Case Study / Postmortem）

项目结束后的案例沉淀有两类：对外营销用的成功案例（强调效果与数据），对内复盘用的 postmortem（强调做错了什么、学到了什么）。两者不能混用——对外不能暴露客户的坑，对内不能只讲成绩。Postmortem 必须遵循无指责原则（blameless），聚焦流程与决策，不点名追责。

49.3.9 README

README 是代码仓库的入口，也是 FDE 最容易忽视的文档。一个好的 README 至少包含：这个项目解决什么问题、怎么在本地跑起来、关键依赖、目录结构、如何测试、联系人。FDE 的原则是"让一个从未见过这个项目的人，在 30 分钟内能在本地跑通"。

49.4 写给不同读者：风格差异矩阵

同一份信息，写给不同读者要换皮。下表是 FDE 常见的四类读者及其偏好：

一个实用技巧：写完任何一份文档后，自问"这份文档的首位读者是谁？他读完能做出什么动作？"如果答不出，文档就是失败的。

49.5 可追溯性：编号体系与交叉引用

FDE 文档体系的核心健康指标是可追溯性——任何一份文档里的结论，都能追溯到上游依据；任何一次决策，都能被下游引用。实现这一点的硬手段是编号体系。

推荐采用四字母前缀 + 年份 + 序号的编码：

• PDD（Project Definition Document）—— 项目定义
• REQ（Requirement）—— 需求条目
• DEC（Decision）—— 决策记录（ADR 是其中一类）
• RSK（Risk）—— 风险登记条目
• DR（Discovery Report）—— 勘探报告
• SD（Solution Design）—— 方案设计
• RB（Runbook）—— 运维剧本

示例：RSK-2026-007 表示 2026 年第 7 号风险条目。周报里写"本周升级 RSK-2026-007"，方案设计书里写"本方案的风险登记见 RSK-2026-001 至 007"，ADR 里写"本决策关联 REQ-2026-023"。这样任何读者顺着编号都能在文档海洋里导航。

版本管理同样关键。每份正式文档应有版本号（v1.0、v1.1）和变更记录表（日期、版本、变更人、变更摘要）。重大变更必须升大版本号，并通知所有相关读者。

49.6 好文档的五个特征

判断一份 FDE 文档好不好，可对照五个特征：

1. 清晰（Clear）：结构分明，每段一个论点，术语第一次出现要解释。检验方法：让一个不熟悉项目的人读 10 分钟，能复述主线。
2. 准确（Accurate）：数据、日期、版本号、指标值必须真实可核对。任何"大约""可能"都要有依据，或明确标注为估算。
3. 可执行（Actionable）：读者读完知道下一步做什么。Runbook 的命令能复制粘贴就跑；周报的求助指名到人。
4. 可检索（Searchable）：标题、编号、关键词能让搜索引擎和同事在 30 秒内找到。避免"最终版_v3_真的最终.docx"这类命名。
5. 可维护（Maintainable）：文档与代码、系统同步更新。一旦系统变了文档没变，文档就从资产变成负债。

49.7 文档即代码：Markdown + git

FDE 应把文档当代码管理。具体做法：

• 所有文档用 Markdown（或 AsciiDoc）纯文本格式，不用 Word 二进制；
• 文档与对应代码放在同一个 git 仓库（docs/ 目录），或独立的文档仓库；
• 文档变更走 pull request 评审，与代码评审同等严肃；
• 用 CI 检查文档（链接是否失效、编号是否重复、术语是否一致）。

这种方式的好处是：版本天然可追溯、变更可 diff、多人协作有冲突解决机制、历史可回溯。客户交付时再导出 PDF 或 Word 即可。

经验法则：如果一份文档没有被 git 追踪过版本，它就不算正式文档。

49.8 用 AI 辅助写作

LLM 是 FDE 写文档的强力工具，但必须用对位置。合理用法：

• 起草：给 LLM 喂入勘探访谈记录、数据样本，让它生成勘探报告初稿；给它架构图描述，让它生成 ADR 草稿。
• 校对：让它检查术语一致性、错别字、格式规范、链接有效性。
• 改写：把一份技术文档改写成 CXO 版本；把中文译成英文交付给国际客户。
• 生成重复结构：批量生成 Runbook 条目模板、培训 FAQ。

必须人工把关的部分：

• 所有数据、日期、版本号、客户名称——LLM 会编造，必须由 FDE 核对；
• 所有结论与建议——LLM 倾向于给出"政治正确但空洞"的表述，FDE 要补上判断与锋芒；
• 所有合规与合同相关表述——必须人工复核，不能交给模型。

原则：LLM 起草，人审发布。署名是 FDE，责任也是 FDE。

49.9 反模式：文档的常见死法

最后列举 FDE 项目中文档的四种典型死法，反向警示：

第一，文档滞后。系统已经升级到 v3，文档还停留在 v1。成因是文档与代码分离管理、没有同步机制。后果是运维按旧文档操作出事。对策：文档进 git、进 CI、进 release checklist。

第二，空洞文档。通篇"提升效率""赋能业务""打造闭环"，没有一个量化指标、没有一条可执行步骤。成因是写文档的人不了解业务。后果是没人信文档。对策：每段必须能回答"so what"。

第三，不可执行文档。Runbook 写"请检查系统状态"，但不写检查哪个看板、用什么命令、阈值是多少。成因是写的人没真正演练过。后果是出事时手忙脚乱。对策：每条 Runbook 必须经过一次实战或演练。

第四，孤岛文档。文档散落在邮件、微信、个人电脑、共享盘、Confluence、飞书，没有统一索引。成因是没有文档治理。后果是新接手的人找不到任何东西。对策：建立单一文档入口（如一个 README 索引页），所有文档有编号、有归属、有版本。

49.10 一张表：FDE 文档能力自检清单

本专题小结

写作与文档能力是 FDE 的核心能力，因为它承载了沟通、留痕、转移、复用四件事。FDE 全流程交付涉及九类必备文档：勘探报告、方案设计书、ADR、周报、交付文档、运维手册、培训材料、案例沉淀、README，每一类都有明确的读者与模板。写给 CXO、技术、一线、采购四类读者要用不同风格，但同一份信息可以换皮复用。可追溯性靠编号体系（PDD/REQ/DEC/RSK/DR/SD/RB）与版本管理实现。好文档具备清晰、准确、可执行、可检索、可维护五个特征。实践上应采用文档即代码（Markdown + git + PR 评审），并合理使用 LLM 辅助起草与校对，但所有事实与判断必须人工把关。最常见的反模式是文档滞后、空洞、不可执行、孤岛化，对应的解药是文档进 git、每段答 so what、Runbook 必演练、单一索引入口。

本专题来源

• CDEF 方法论（Context 勘探 → Design 设计 → Engineer 工程 → Feedback 反馈）各阶段交付物定义；
• Michael Nygard 提出的 ADR（Architecture Decision Record）格式与社区实践；
• Palantir、Databricks 等 FDE 型公司的内部文档传统（Echo-Delta 双人单元的留痕习惯）；
• 软件工程的"Docs as Code"运动与 GitLab、Google 等公司的文档工程实践；
• 个人驻场项目中九类文档的实际模板与踩坑复盘；
• Site Reliability Engineering（Google）中关于 Runbook 与 Postmortem 的规范；
• LLM 辅助写作实践中"起草—校对—人审"分工的工程经验。