技术笔记怎么写得容易接着读、接着做

写作那几页既记了句子和段落，也记了“下一步必须现在可执行”“超过五条拆成 now/later”。它们关心的是同一个实际场景：读完一段文字，能不能知道它讲了什么、接下来做什么。

一段话只做一件事

一个段落可以解释一个概念，也可以讲清一次失败。要交代为什么选这个方案，就另起一段，让理由展开。标题和开头要是重复同一个意思，读者得往后走很久才碰到新信息。

想要一条能当场自查的规则，可以借 Google 开发者文档风格指南的段落一节：一段超过五六句，通常说明装了太多；重点放段首，别压到段尾。改稿时不妨先数句子，数完往往就知道哪里该拆。

开头说明读者需要什么背景，正文按理解顺序展开。缩写第一次出现时解释，代词指向要明确。同一份指南对代词的建议很实用：“这个”“这些”后面最好再跟一个名词，写成“这个参数”，读者就不用回头猜（代词一节）。长文再用目录和路标句帮人定位，不必每一节都重新介绍全文目标。

列表适合并列的项目。项目之间是因果或连续过程时，就得把连接写出来：加点只是版式上把一条条分开，不等于它们各自独立，因果和先后还得靠词句自己带。每句话前面加一个点，结构不会自己长出来。

图先限定范围，再补说明

给图写图注时，往往就能发现这张图是不是装了太多内容。手绘图里一个箭头可能同时承担时间、依赖和分类关系，重画时先定下它到底表达什么。总览图展示范围，流程图交代顺序，调用关系另画一张。

C4 模型把这件事讲成了分层：不同缩放层级讲不同的故事、给不同的读者，用不着每层都画。最外层的系统上下文图给技术和非技术的人一起看，故意不放技术细节。拿它当判据：一张图只服务一个层次、一批读者。

图注本身也是检验。Google 指南的图片一节要求图注是简洁而完整的概括，正文还要用完整句子引出图，并用文字复述图里的信息。一句话概括不了的图，多半是塞了两件事。

代码示例也要交代范围：片段是示意还是可运行代码，省略了什么输入，该看哪个结果。示例短，不一定就好懂：把关键条件删了又不说明，读者照着跑不起来，也判断不出这个例子在什么前提下成立，只能自己往回猜。代码示例规范的做法是用该语言的注释标出省略，不用三个点；占位符第一次出现就说明代表什么。

写作里的判断留给自己

LLM 能帮着重排章节、校订文字、查找不一致，也能按指定长度总结。但我记下了一个顾虑：外包出去之后，写作本身带来的思考也就没了。初稿尤其如此，描述需求的过程常常会暴露哪些概念没想清楚。

这个顾虑有研究可以对照，两边的证据都要摆出来：

第一项测的是产出的速度和质量，后两项测的是写的人自己想了多少、记住多少，并不矛盾。工具确实让成品更快更好；我在意的是写的过程里那份思考，后两项正好指向它会变少。

所以先写自己要表达的内容，再让工具帮着检查，更容易看出它改了哪里。手上有一份自己写的版本，工具改了哪句、漏了哪层意思，两边一比就知道。初稿要是工具写的，少了这份底稿，就只能拿需求、材料、提纲回去一条条查，没那么容易看出来。

引用、经历和效果都要能回到材料。总结完再查每条信息来自哪一段，也能发现那些看似合理、实际没有出处的补充。Kosmyna 那项实验里，LLM 组连自己文章里的句子都引不准，没有自己写的底稿，这一步核对就无从下手。

下一步要写到现在就能动手

工作安排上记下的几种方法，都从一个具体困难入手：

• 记不住状态，就重述当前状态；
• 知道该做却启动困难，就把下一步写小；
• 旁支太多，先收进稍后列表；
• 完成感不清楚，就明确指出目前哪些产物已经可用。

下图箭头左边是遇到的困难，右边是可以尝试的调整。

flowchart LR
  memory["忘记当前状态"] --> recap["重述已完成和下一步"]
  start["下一步太大"] --> action["写成现在可执行的小动作"]
  branch["旁支越来越多"] --> later["分开当前任务与稍后列表"]
  finish["不知道是否可用了"] --> usable["明确可用产物与剩余限制"]

这些方法也适合检查自己的笔记。标题下面只有一句“完善设计”，隔几天再读很难开始；写成“补上提交失败后的页面状态”，就知道该回到哪里接着做。

这几种方法各自都有更正式的说法，可以拿来校准：

• 下一步写多小：GTD 对“下一步行动”的定义是下一个物理的、看得见的动作，不是项目名。“完善设计”是项目名，“补上提交失败后的页面状态”才是动作。
• 启动困难：实施意图（if-then 计划）把情境和动作绑在一起，“遇到 Y，就做 Z”。美国国家癌症研究所的概念页引 Gollwitzer 和 Sheeran 2006 年的元分析，94 项研究里它对目标达成的效应量 d = .65，专门针对“启动不了”的是 d = .61。
• 完成感：Scrum 的完成定义是增量达到质量标准时的正式描述，没达到的条目不能发布，也不能拿到 Sprint Review 上展示。先写下“算完成”的标准，再说哪些产物可用。

所以写下一步时，我会把它写成“明天打开项目，先补上提交失败后的页面状态”这样的句子：有情境，有动作，做完能看见。