技术文档怎么写，别人才愿意看完
文档的第一读者不是领导，是三个月后需要照着做的同事。先想清楚他要拿这篇文档做什么决定。
怎么做
把散落笔记整成能用的提纲
把零散笔记、会议记录和链接一起贴进「把散乱想法整理成结构」。要一句话主旨、三到五个部分（每部分解决什么问题）、每个碎片归位，并指出哪两个想法重复或互相矛盾。提纲确认之后再动笔，能省掉大段返工。
让标题替读者划重点
把初稿给「给长文加小标题」。让它先标出话题真正转换的位置，不要按段落平均切；每个标题八到十四字、用陈述句，只看标题就知道这一节回答什么。找不到主题的段落，要么合并要么删掉，它会把新增和改动列出来。
逐句核对断言和证据
把带判断的段落给「检查断言与证据是否匹配」。它会区分事实、趋势、因果和预测，标出证据类型，指出用一个案例支撑「所有」、用相关性证明因果的地方。每条不匹配都要给降级措辞或补证据的建议，不要直接改写。
按读者身份重写一遍
明确读者是谁（产品、客户还是管理层），把技术部分给「技术文档改给非技术读者」。开头一句说清这对读者意味着什么，术语第一次出现时用日常经验解释，限制条件、失败情况和数字都要保留，歧义和缺失单独标「需确认」。不要用比喻替代机制。
找个没耐心的读者试一遍
最后用「假装是随时会关掉页面的读者」，设定读者身份，让它按顺序读并回答：读到第几段会关、哪句话让人失去耐心、哪三处在自说自话、哪个论点作者自己没想清楚、只留一半删哪几段。按这个结果删，而不是继续加内容。
用到的提示词
常见问题
技术文档写多长合适
取决于读者要拿它做什么决定。能让读者在需要的地方停下并找到答案，比篇幅重要。第 5 步通常会让你发现，被删掉的段落读者本来也不会看。
文档里的架构图要不要用 AI 画
可以，但先用第 1、2 步把结构和标题定下来再画。否则图会跟着散乱的思路一起乱。图里每个箭头都应该能在文字里找到对应的机制说明。
给非技术读者写，是不是要删掉风险
不要。第 4 步要求保留限制条件、失败情况和数字，只把实现细节换成读者能对应的后果。删掉风险的文档，会在真出问题时失去信任。