你为一份技术文档模板而来——一份新工程师真能照着上手的文档的结构。它在下面；抄走。但技术文档有所有文档里最严重的漂移问题：它描述一个每天都在变的系统，而文档是人手更新的、在某人想起来时、也就是很少。一个 sprint 内文档和代码就对不上，读者分不清该信哪几段。Draftlize 给你同样的结构，把文档背后的决策做成卡片，在系统越过它们时去标记。
好的技术文档大致按这个顺序回答读者所需——从「这是什么」到「它着火了我该怎么办」。不是每份文档都要全八节；不适用的跳过。
这个系统或组件是什么、解决什么问题、给谁用——用新人能先读的几句话。如果读者从顶部判断不出这份文档跟自己有没有关系，后面的就不会被读。
到可运行状态的最快路径——前置条件、安装、一个能跑的最小示例。流量最高的一节；狠狠优化它，因为失败的头五分钟正是大多数读者离开的地方。
各组件、它们如何交互、以及这个形状背后的关键决策——最好配图。这一节能替工程师省下一周，也是和「会变的决策」绑得最紧的一节。
端点、函数、参数、返回值、错误。详尽而精确；这是查阅材料，不是叙事。尽量从源码生成，让它无法悄悄落后。
环境变量、设置、开关——每个干什么、默认值、合法取值。是人们凌晨两点 grep 的那一节，所以完整胜过文采。
怎么部署、监控、扩容、恢复——运维的现实，而不只是顺路径。仪表盘是什么意思、告警是什么意思、各自触发时该做什么。
常见故障及其修复，写自真实事故。把 30 分钟的宕机变成 3 分钟的那一节——也是随故障模式变化最先过时的一节。
改了什么、何时、归谁。告诉读者「这文档到底能不能信」的元数据——一份一年没动过的文档是警告，不是参考。
代码天天变，文档在某人想起来时才变。缝隙立刻打开、不断累积。和多数文档不同，技术文档旁边就有一个权威真相源——代码——而落后的永远是文档那一边。
一份 80% 正确的文档，比一份缺失的更危险，因为读者信了错的那 20%。没有「哪几节是当前的」这个信号，整份文档会被悄悄不信任——然后人们干脆不写文档了。
架构那一节解释一个设计决策——为什么用这个队列、为什么这条边界。当那个决策在代码里被推翻，没有任何东西告诉文档。解释活得比它解释的东西还久，自信地描述着一个已不那么运作的系统。
在 Draftlize 里，文档中的架构和设计理由是连着真实决策的卡片——「这里用队列是因为……」指向那张决策卡，而不是一段凭记忆重打的文字。文档引用决策，而不是复制它。
在代码里推翻设计决策，解释它的那个文档章节自动标记 stale——就像构建系统让被改文件的下游全部失效一样。读者拿到一个信号，而不是去信一段如今已错的自信文字。
Claude Code 或 Cursor 在动代码前经 MCP 读相连的决策——于是 agent 基于「当下的架构」工作，并在它改了设计时把决策写回去，让文档和代码保持同一个版本。
技术文档是唯一一种「真相就在旁边的代码里」的文档——而落后的永远是它。留着这个结构，把文档连到决策，让代码能去标记它 stale。
概述与目的、快速开始、架构、API 或参考、配置、运维手册、排障，以及带负责人的变更记录。不是每份都要全有——让章节匹配读者真正需要的。
技术设计文档（TDD）是在构建之前写、用来提出并对齐一种方案；技术文档描述已建成的系统，给使用或维护它的人。TDD 是一个决策，文档是一份参考。
尽量从源码生成参考材料，让文档贴近代码（docs-as-code），并把解释连到它们所依赖的决策，好让一次改动去标记受影响的章节。失败方式是手工维护的散文，且没有「哪些部分还成立」的信号。
把文档当源码对待——用 Markdown 等纯文本格式写、和代码一起放进版本控制、在 PR 里评审、用流水线构建。它让文档更贴近变化、让漂移更可见，但它本身并不能消除漂移。
用上面的结构，或把文档背后的决策作为卡片放进 Draftlize、连着设计——这样代码一旦推翻某个决策，解释它的文档章节就标 stale，你的编码 agent 永远读到当前架构。
$5 免费开始