写"通俗易懂又有深度"技术文档的 Prompt 指南

目标:让 AI 产出的技术文档,既能让不了解该技术的人读懂,又能把底层机制、来龙去脉、边界代价讲透。 本文本身尽量遵循下面列出的所有原则,可当作一个"样例文档"来看。

---

0. 先厘清一个核心矛盾

"通俗"和"有深度"经常被当成对立面,于是产生两种常见的失败文档:

• 稀释型:为了通俗,把概念泡在生活化比喻里,读完感觉"好像懂了",但一遇到真实场景就用不上。
• 堆砌型:为了显得有深度,堆术语、贴定义、罗列 API,读者根本进不去。

这两者的病根其实是同一个:没有把"为什么"讲清楚。 通俗不等于稀释深度,深度也不等于堆术语——真正的解法是用精准的语言,沿着因果链把机制讲明白。下面所有原则都服务于这一句话。

---

1. 从读者出发:开篇声明"前置知识"与"学习收获"(最重要)

原则:每篇文档的最开头,必须显式列出两件事——读懂它需要的前置知识/能力,以及读完后能获得的知识/能力。

这是排在所有写作技巧之前的第一原则。原因很直接:

文档写得再好,只要它和读者已有的知识水平错位,读者依然看不懂。"看不懂"的根因往往不是文档不够好,而是写作者不了解这位读者——没有针对他的水平来定制。

所以在动笔之前,必须先把读者的坐标定下来。这个开篇声明有两层作用:

• 对读者:一眼判断"这篇现在适不适合我读"。前置知识里有我不会的,我知道该先去补什么;学习收获正是我想要的,我就放心读下去。它还是个诊断工具——如果读完还是没懂,多半是前置知识列错了(定高了或漏了),下次据此校准。
• 对写作者(尤其是 AI):前置知识 = 可以直接使用、无需解释的概念;学习收获 = 本文必须交付的目标。这两条边界一旦划定,就知道哪些该展开、哪些可略过、写到什么程度算完成,从而既不会把读者当小白反复解释基础,也不会默认读者全懂而跳步。

放在每篇文档最前面的开篇模板:

## 读前须知

**前置知识 / 能力**(具备这些才能顺畅读懂):
- 了解 X 的基本概念(例:知道什么是 HTTP 请求)
- 能读懂基础的 Y 代码(例:Python 的函数定义与调用)

**读完你将获得**:
- 理解 A 的工作机制,能说清它为什么比 B 快
- 能独立完成 C(例:自己配置一个反向代理并验证生效)

一个关键要求:两个清单都要具体、可自我检验,不能写"了解编程基础"这种模糊表述——读者要能对着每一条明确判断"这个我到底会不会"。

关键动作:动笔前主动摸底,而不是被动假设

只靠读者自己声明水平是不够的——读者常常"不知道自己不知道"。所以写作者应该针对本主题真正必需的前置项,用具体的封闭式问题逐条来问,而不是笼统地问"你基础怎么样"。例如:

• "你了不了解 X?"(某个概念)
• "能不能读懂这样的 Y 代码?"(某种能力)
• "有没有做过 Z 这类事?"(某种经验)

拿到回答后分两种情况处理——这也顺带回答了第 2 条"禁止比喻"留下的疑问:到底什么时候能用类比?

• 读者已经掌握的技术 → 可以拿它作恰当类比的基准("这部分机制和你熟悉的 X 是同一类,区别在……")。这是唯一被允许、且非常有效的类比:锚定在读者已有的真实技术经验上,而不是生活场景。
• 读者没接触过、但本文必需的技术 → 不能默认他会,要在开头先做简要介绍,把它立成后续讲解的抓手。

一句话:类比落在读者已知的技术上,空白在开头补成抓手。 至于为了类比而类比、牵强的跨域比喻,依然禁止。

写进 prompt 的话:"动笔前,先针对本主题必需的前置项,用具体的封闭式问题逐条问我(如'你了不了解 X''能不能读懂这样的代码''有没有做过这类事'),而不是笼统问我水平如何。然后在文档最开头设置'读前须知',用两个清单写明:① 读懂本文需要的前置知识/能力(具体到我能逐条自查,而非'有编程基础'这类模糊说法);② 读完本文我能获得的知识与能力。根据摸底结果:我已掌握的技术,可作为恰当类比的基准帮我理解新概念;我没接触过、但本文必需的技术,要在开头先介绍作为抓手,不能默认我会。把前置知识清单里的概念当作可直接使用、无需解释;把学习收获清单当作本文必须交付的目标。若我声明的水平与主题难度不匹配,先提醒我再动笔。"

---

2. 语言:精准、严谨,禁止跨域比喻

原则:用本领域的精确术语和定义说话,不用生活化类比来"降低理解门槛"。

需要区分三种情况:

• ❌ 跨域生活化比喻(禁止):"线程就像餐厅里的服务员……" —— 比喻本身不精确,牵强时反而制造新的误解,而且掩盖了"你本来想问的底层是什么"。为了类比而类比,同样禁止。
• ✅ 本领域具体实例(必须保留):一段真实的代码、一个真实的调用场景、一组真实的数值。实例是"具体化",不是"打比方",它让抽象概念落地,同时保持精确。
• ✅ 类比到读者已掌握的技术(允许且鼓励):当第 1 条的摸底确认读者已经会某项技术时,可以拿它作类比基准("这部分机制和你熟悉的 X 是同一类")。这类类比锚定在读者真实的技术经验上,不是生活场景,因此精确、有效。

写进 prompt 的话:"解释概念时使用精确的技术术语和本领域的具体实例;禁止使用与本领域无关的生活化类比,也禁止为了类比而类比。唯一允许的类比是类比到我已确认掌握的技术概念。确需类比才能说清时,先给出精确定义,再补充说明这是近似。"

---

3. 先讲来龙去脉与痛点(横向:历史)

原则:介绍一项技术前,先用几句话交代它的上下游发展脉络和它主要为了解决什么痛点。

一项技术是对前一项技术的局限的回应。不讲这个,读者就只能死记"它是什么",而无法理解"它为什么长这样"。顺序建议:

1. 在它之前,人们用什么?那个方案的痛点/瓶颈是什么?
2. 这项技术出现,主要解决了上面哪个痛点?代价是什么?
3. 它现在的上下游/替代者是什么?(可选,帮助定位)

写进 prompt 的话:"介绍每项技术前,先简述:它出现之前的方案及其痛点 → 它主要解决了什么问题 → 为此付出了什么代价。"

---

4. 分层递进的深度(纵向:允许下钻)

原则:内容按"是什么 → 为什么 → 怎么用 → 底层机制 → 边界与坑"分层组织,让读者能在需要的深度停下。

这与第 3 条正交:历史是横向的时间线,分层是纵向的深度。分层的好处是同一篇文档同时服务不同水平的读者——只想会用的读到"怎么用"即可,想深入的继续往下钻。

层次	回答的问题	面向
是什么	一句话精确定义	所有人
为什么	解决什么痛点、为何这样设计	所有人
怎么用	最小可用示例	使用者
底层机制	内部如何运作、为什么这样就快/安全	深入者
边界与坑	何时不该用、有哪些陷阱	深入者

---

5. 讲机制,不只给结论(深度的硬指标)

原则:凡出现"更快 / 更省内存 / 更安全 / 更可靠"这类判断,必须给出因果链,而不是只丢结论。

这是"有深度"最容易被偷懒的地方。判断一段解释有没有深度,就看它能不能回答连续的"为什么":

• 结论:"用索引查询更快。"
• 有深度:"更快,是因为索引把数据组织成 B+ 树,查找从 O(n) 的全表扫描变成 O(log n) 的树遍历;代价是写入时要额外维护树结构,且索引本身占用存储。"

写进 prompt 的话:"任何性能/安全/可靠性方面的结论,都必须给出导致该结论的机制(因果链)和相应代价,不接受只给结论。"

---

6. 定义简洁,分析用"自问自答"引出

原则:定义写得简洁精准;而说明与分析通过提问引入,用自问自答把读者带进思考。

这是控制节奏的关键。好的技术文档不是平铺直叙,而是不断制造"认知缺口"再填上它。提问的三种典型用法:

• 暴露旧方案的裂缝:"上面的做法在单机下没问题——但如果并发请求同时修改同一条数据,会发生什么?"
• 点破常见误区:"很多人以为 == 和 === 只是写法差异,真的如此吗?"
• 引出新痛点:"既然缓存这么好,为什么不把所有东西都缓存起来?"

提问之后立刻给出精准的自答。定义收敛,分析发散——两者节奏不同,不要混在一起写。

写进 prompt 的话:"定义要简洁精准、单独成段;涉及'为什么/什么场景会出问题/常见误区'的分析,用自问自答的方式引入,先抛出读者此刻最可能有的疑问,再精准回答。"

---

7. 关键关系用示意图

原则:当涉及多个实体之间的关系、流程时序、层次结构时,用示意图表达,不要只用文字堆砌。

文字擅长线性叙述,不擅长表达"谁指向谁、谁包含谁、先后顺序"。这类结构用图一目了然。纯文本环境优先用 Mermaid / ASCII:

graph LR
    Client[客户端] -->|请求| LB[负载均衡]
    LB --> S1[服务A]
    LB --> S2[服务B]
    S1 --> DB[(数据库)]
    S2 --> DB

判断标准:如果一段话里出现 3 个以上实体且它们互相有关系,就考虑画图。

写进 prompt 的话:"涉及多个实体的关系、调用时序、层次结构等难以用文字线性表达的地方,用 Mermaid 或 ASCII 示意图表示实体之间的关系。"

---

8. 代码/命令:注释 + 输入-输出-结果 三件套

原则:每段代码或命令行示例都要有恰当的注释,并附上模拟的输入、输出、运行结果。

读者看代码最想知道的是"这段到底干了什么、跑出来长什么样"。缺了输入输出,代码就只是静态文本。示例:

# 统计当前目录下所有 .log 文件的总行数
wc -l *.log

输入(当前目录):app.log(120 行)、error.log(30 行)

运行结果:

 120 app.log
  30 error.log
 150 total

说明:wc -l 按文件分别计数,最后一行 total 是汇总。这样读者不必自己运行就能确认行为是否符合预期。

写进 prompt 的话:"每段代码/命令都要:① 关键行有注释说明意图;② 给出模拟输入;③ 给出运行结果;④ 一句话说明结果为什么是这样。"

---

9. 讲清适用边界与取舍(何时"不该"用它)

原则:每项技术都要说明它的适用边界、反模式、代价——什么场景下它是错误的选择。

只讲优点的文档没有深度,因为真实工程决策全在权衡里。要覆盖:

• 它不适合什么场景?
• 有哪些常见的误用/反模式?
• 采用它需要付出什么代价(复杂度、性能、维护成本)?

写进 prompt 的话:"每项技术都要说明其适用边界、典型反模式,以及采用它的代价;明确指出什么场景下不应使用它。"

---

10. 可核验 + 版本意识 + 诚实标注不确定(防"一本正经地编")

原则:区分"确定的事实"与"推断";涉及具体行为要标明版本;拿不准就明说,不要自信编造。

这是给 AI 写技术文档时最致命的风险:模型会用同样流畅自信的语气输出正确的和编造的内容。约束它:

• 陈述具体行为、默认值、API 时,尽量指明来源/规范/版本(如"自 Python 3.7 起 dict 保持插入序")。
• 区分"这是标准行为"和"这是我的推断/常见实现"。
• 不确定就说不确定,并指出读者可以去哪里核实,而不是给一个看似确定的假答案。

写进 prompt 的话:"陈述具体行为、默认值、性能数字时,标明适用的版本/规范;区分确定的事实与你的推断;若不确定,明确说明并指出核实途径,禁止用确定的语气输出未经确认的内容。"

---

11. 术语一致 + 阶段性对比总结

原则:同一概念自始至终只用一个词;在概念积累到一定程度时,做回顾性对比或总结。

• 术语一致:一个概念一个名字,首次出现时给出业界的其他别名(如"这里的'协程'在部分文档里也叫'纤程'"),之后统一用一个。
• 阶段性总结:当读者已经接触多个概念后,适时停下来梳理。是否用表格,看两个条件:

情况	用什么
概念之间差异很大、不易混淆	用文字小结即可,不必上表格
概念相近、初学者容易分辨不清	用表格逐维度对比(如进程 vs 线程 vs 协程)

写进 prompt 的话:"同一概念全程使用统一术语,首次出现时注明常见别名;每积累若干新概念后做一次回顾。仅当多个概念相近、易混淆时才用表格逐维度对比,差异明显时用文字小结。"

---

附:可复用的 Prompt 模板

把上面的原则拼成一段可直接使用的指令。使用时替换 【】 中的内容:

请为我写一篇关于【主题】的技术文档。我已经掌握【前置知识】,但不了解【本主题】,读完希望能【目标能力】。

请严格遵循以下要求:

1.  【读者定位,最重要】动笔前,先针对本主题必需的前置项,用具体的封闭式问题逐条问我(如"你了不了解 X""能不能读懂这样的代码""有没有做过这类事"),而不是笼统问我水平如何。然后在文档最开头设置"读前须知",列出两个清单:① 读懂本文需要的前置知识/能力(具体到我能逐条自查,而非"有编程基础"这类模糊说法);② 读完本文我能获得的知识与能力。根据摸底结果:我已掌握的技术可作为类比基准;我没接触过、但本文必需的技术要在开头先介绍作为抓手。把前置知识当作可直接使用、无需解释;把学习收获当作必须交付的目标。若你判断我声明的水平与主题难度不匹配,先提醒我再动笔。
2.  【语言】用精确的技术术语和本领域的具体实例;禁止与本领域无关的生活化比喻和为了类比而类比,唯一允许的类比是类比到我已确认掌握的技术。
3.  【来龙去脉】开头先简述:本技术出现前的方案及其痛点 → 它主要解决了什么问题 → 为此付出的代价。
4.  【分层】内容按"是什么 → 为什么 → 怎么用 → 底层机制 → 边界与坑"组织,让我能按需下钻。
5.  【讲机制】任何"更快/更安全/更省"之类的结论都要给出因果链和代价,不接受只给结论。
6.  【节奏】定义简洁、单独成段;分析用自问自答引入——先抛出我此刻最可能的疑问(旧方案的裂缝、常见误区、新痛点),再精准回答。
7.  【图】涉及多实体关系、时序、层次结构处,用 Mermaid 或 ASCII 示意图表达。
8.  【代码】每段代码/命令都要有注释、模拟输入、运行结果,并说明结果为何如此。
9.  【边界】说明每项技术的适用边界、反模式和代价,指出什么场景不该用它。
10. 【可核验】陈述具体行为/默认值/数字时标明版本或规范;区分事实与推断;不确定就明说,禁止自信编造。
11. 【术语与总结】同一概念全程用统一术语(首次注明别名);概念积累后做回顾,仅在概念相近易混淆时才用表格对比。

如果我给的前置知识、目标或范围不够明确,先向我提问确认,再开始写。

---

一页速查(勾选清单)

• 动笔前是否用具体问题摸底了必需的前置项?开头是否列出了"前置知识"和"学习收获"两个清单?每条是否具体到可自查?(最重要)
• 语言是否精确?是否只在读者已掌握的技术上做类比、无跨域/牵强比喻?本领域实例是否保留?
• 是否讲了痛点与历史脉络?
• 是否分层、可下钻?
• 每个结论是否都有因果链和代价?
• 定义是否简洁?分析是否用自问自答引出?
• 多实体关系处是否有示意图?
• 代码是否有注释 + 输入 + 输出 + 结果解释?
• 是否讲了适用边界和"何时不该用"?
• 是否标明版本/来源、诚实标注不确定?
• 术语是否一致?是否在恰当处做了对比总结(必要时用表格)?