文档与决策记录：让下一次接手的人知道怎么做、为什么这样做

小叶用AI做了一个温度记录绘图小工具。把实验记录选进去，点一下按钮，就能得到温度随时间变化的图。自己做报告时，他已经用过几次。另一位同学想借来使用，小叶便把程序和一份说明发了过去。说明的开头写着：“本系统支持实验数据可视化，具有便捷、高效、易于扩展的特点。”

同学看完仍然不知道第一步怎么做。文件应该有哪几列？时间填秒还是分钟？图画不出来时要改哪里？生成的新文件在哪里？他问过小叶，终于画出了图，又发现图上的温度与自己预期的不同：他以为工具会把起始温度调整为零，小叶做的却是保留原有温度。程序没坏，但两个人对程序做了什么没有形成一致理解。

一个月后，小叶自己也遇到了接手困难。他请AI整理程序，AI看到早期聊天中的“把输入中不参与绘图的列删掉，再直接保存，文件看起来更整齐”，准备加入这个整理步骤。小叶记得后来放弃了这个方案，却想不起当时把理由写在哪里。代码留下了最后的做法，讨论留下了许多说法，真正支持接着做事的信息反而散在各处。

本章讨论的文档，就是为这些时刻准备的。我们要学习怎样让别人独立开始使用，怎样说明结果的含义，怎样留下重要选择的理由，以及怎样使这些说明随着项目变化仍然可信。下文的工具、版本、数据和交接过程均为教学设定，不是真实产品的使用记录。它们帮助我们看清文档在具体工作中起什么作用。

一、先找到读者卡住的动作，才能知道该写什么

软件文档是围绕软件的使用、理解和修改而保留的说明。它可以是一页起步指南、一段输入要求、一份重要决定的记录，也可以是贴近代码的注释。把它们放在一起的理由，是有人需要借助这些信息完成某件事。格式再规范，如果那个人仍然无法行动，文档就没有完成自己的工作。

小叶最初写的介绍主要回答“这个项目听起来怎么样”。同学当前的问题却是“我手上的记录能不能直接放进去”。这两类问题需要的信息不同。前者可以用功能概述回答，后者必须知道文件内容、单位和操作入口。把“高效、智能、便捷”换成更漂亮的形容词，对同学开始使用几乎没有帮助。

可以把读者的需要沿一次使用过程展开。同学还没下载时，需要判断工具是否适合自己的任务；刚打开时，需要完成第一张图；换用真实记录时，需要确认数据含义；准备交报告时，需要知道图上显示了什么；后来改工具时，又需要知道某些限制为何存在。读者的动作变了，值得提供的信息也随之变化。

这会改变写作顺序。小叶不必先照着大型软件的文档目录，把项目背景、行业现状、总体架构全部写完。他可以先陪同学走一遍“拿到程序到得到可解释结果”的过程，记下停住的位置。输入单位不明，就补单位；不知道结果去哪了，就补结果位置；不理解为何不能覆盖输入，就保留这一选择的理由。每一项说明都有一个具体的使用时刻。

不过，写文档也不只是收集已经有人问过的问题。有些错误不会触发提问。把一分钟填成数字1，工具可能照常生成一张图；如果它把1理解为一秒，使用者甚至会以为自己成功了。因此，需要同时考虑两类信息：缺少它会让人做不下去的信息，以及缺少它会让人做错却不自知的信息。后者往往更值得尽早写明。

同一项目的使用者和修改者，也不需要同时读完所有资料。只想画图的同学，通常不需要先了解程序内部每个函数。准备新增输入格式的同学，则需要找到数据读取部分和现有约定。文档可以提供不同入口：先让人完成当前任务，再把相关的深层说明接到他需要的位置。这样既保留深度，也避免让第一次使用变成阅读全部设计资料的考试。

这里有一个很实用的判断方法：写完一段后，试着说明“读者看到这段以后，能少猜哪件事，或多完成哪一步”。如果答案只是“显得完整”，就该重新考虑它的位置和内容。反过来，一段只有几句话的说明，如果能避免把时间单位读错，它的价值可能远高于几页项目愿景。

二、起步说明要带人走到第一个能判断的结果

项目中常见的README，可以理解为放在入口处的阅读说明。它先帮助新来的人认识项目、开始使用，并找到进一步的信息。GitHub对README的说明也把用途、起步方式、求助与维护信息列为常见内容。这里借用的是入口的作用，不要求每个小项目都采用同一种目录结构。GitHub：关于README。

为使后面的讨论有固定对象，先规定小叶当前交出的版本叫R1。它在本地读取CSV文件，至少需要time_s和temperature_c两列，分别表示以秒计的时间和以摄氏度计的温度。它要求这两列都有有效数值，时间严格递增；遇到不符合要求的数据，会停止并指出位置。其他列不参与绘图，仍保留在输入文件中。使用者先新建一个空结果文件夹，再在程序中选中它；R1把图像和本次处理说明写进去，保留输入文件原样。R1还没有把起始温度调整为零的功能。

小叶为R1提供一个程序包，包内有启动程序、示例文件和说明。这里不展开如何打包，先设接手同学的电脑已满足随包说明列出的运行条件。起步说明可以写：“这个工具把一组时间与温度记录画成折线图。打开包内名为‘温度绘图工具’的启动程序，点击‘选择文件’，选中附带的示例CSV。新建一个空文件夹，通过‘选择结果目录’选中它，再点‘生成’。完成后打开这个文件夹查看图片和处理说明。”启动名称和按钮是本例的设定；实际项目应与交出的程序相符。接着给出示例的预期结果，同学就能判断是否完成了这条路径。

示例不宜塞入很多数据。为了让人看清输入与输出的关系，附带文件只放下面三条虚构记录。表头就是文件里的列名。

这三条记录表示：开始记录时是20摄氏度，三十秒时是21摄氏度，一分钟时是22摄氏度。起步说明告诉同学，生成的图应当以秒为横轴、摄氏度为纵轴，依次经过这三个记录点。这样，他既知道点按钮以后去哪里看结果，也知道看见什么才与当前输入相符。

只有操作步骤而没有预期结果，使用者容易把“出现了一个文件”当作成功。补上预期结果，并不是要求他第一次使用就检验全部程序，而是提供一个简单的判断支点。如果最后一个记录点位于60秒，起点温度为20摄氏度，便与这个示例的含义相符；如果起点自动变成零，就应该回头核对打开的版本或处理设置，不能仅凭图画出来了就继续交付。

起步说明还应讲清成功后的文件关系。例如，R1把图片保存为temperature.png，把输入名称、所用单位和处理方式写在同一结果目录的run-note.txt里。这些名称是案例中的约定。同学打开新结果目录就能看到这两个文件，原来的示例文件仍在原位置。文档不用让他猜输出是否悄悄覆盖了输入，也不用让他在整个电脑里寻找一张不知叫什么的图。

第一次起步最容易漏掉的，是作者已经做过、读者却尚未做过的准备。小叶的电脑里可能已有运行所需环境，而同学的电脑没有；小叶知道按钮藏在哪个窗口里，同学只看到几个陌生文件。实际交付时，起步说明应写适用的系统、所需环境或安装入口，并按交付包核对。不能把本机已经具备的条件，变成“正常打开即可”里的隐藏前提。

因此，最小示例的“小”，指的是把任务缩到能清楚走完，而不是省略完成它所必需的条件。一份好用的起步说明，会让读者建立第一条完整经验：找到入口，准备输入，执行动作，识别输出。后面的复杂内容，可以接在这条经验上展开。

三、把数据的含义写出来，结果才有共同的解释

同学已经能用示例画图，接着换成自己的实验记录。这时，最小示例提供的直觉还不够。他的表格写着“时间”和“温度”，时间以分钟计。如果只是把列名改成工具接受的英文名字，数字的含义并不会自动改变。原来表示一分钟的1，会被R1按一秒解释。图仍然可能很整齐，时间尺度却已经错了。

输入约定需要同时说明形式和含义。形式回答有哪些列、哪些位置需要数值；含义回答这些数值描述什么、采用什么单位、哪些条件必须满足。time_s中的字母能够提醒熟悉写法的人，但不能要求初学者仅凭缩写猜出完整规则。文档应直接说明：这一列是秒，若原始记录采用分钟，需要先得到对应的秒数，再交给当前工具。

这个案例中，0、0.5、1分钟对应0、30、60秒。重要的关系是：同一段实验经过了同样长的时间，只是改用另一种单位记录。调整后的数据让工具正确理解时间尺度，不能只换表头而保留原数字。若要保留原始实验记录，可以另存转换后的输入副本，并记下它来自哪份原记录。R1自身保留输入的约定，不等于使用者在导入前所做的改动也自动被记录了。

缺失值同样需要明确处理方式。假设中间一条记录没有温度，使用者可能以为工具会跳过这一条，也可能以为会补一个数。R1的规定是停止并报告缺失位置。文档应告诉他当前会发生什么，以及接下来应核对哪份记录。它不能建议“随便填零再画”，因为零摄氏度是一项有实际含义的测量值，用它代表没记录会改变图的内容。

时间严格递增也是当前工具的输入要求。若记录里两行时间相同，R1拒绝继续。读者需要知道这是这版工具的处理范围，便于回查重复行究竟来自录入错误，还是实验确实进行了同一时刻的多次测量。后者可能需要另选合适的数据整理方法。不能为了通过工具检查，就把有意义的记录随意删掉，更不能把本工具的限制讲成所有实验数据都必须遵守的科学规律。

输出约定则回答另一半问题：工具生成的结果代表什么。R1画的是输入中的原有温度，没有减去起始温度，也没有自动剔除看起来奇怪的记录。图上升高，表示输入记录的温度升高；图的起点为20摄氏度，并不表示程序没有“校准好”。如果使用者想比较不同实验相对各自起点的变化，需要另作处理选择。

这也是为什么文档要给输出命名加上解释。只有“处理完成”四个字，不能帮助人区分按原值绘图、平滑后绘图或调整起点后绘图。小叶可以在处理说明里写明“按输入温度绘图，未调整起始温度”，并保留输入文件名称。这样，过几天再打开图片的人仍有机会查清这张图从哪里来、做过什么处理。

输入输出约定经常与接口说明相连，但本章关心的不是再设计一遍接口，而是把会影响行动和判断的含义留下来。文件能被读取，只说明形式上被程序接受；图能被保存，也不自动说明使用者已经正确解释了它。文档要把这两端接起来，让“能运行”逐步成为“知道自己运行了什么”。

四、为什么代码、注释和使用说明不能互相包办

有人会问：既然代码已经写明程序怎样处理数据，为什么还要另外说明？对于准备修改程序的人，读代码确实是重要的信息来源。但是，同学只是想完成一张图，不应先把数据读取、检查和保存代码全部研究一遍，才能知道温度是否被调整。把所有理解责任交给代码，会把使用门槛抬到不必要的高度。

更关键的是，代码通常比较直接地表现“现在怎么做”，却不一定保留“为什么选了这种做法”。例如，程序只读取输入，再把输出写到新目录，读者能够找到这些动作，却未必知道保留输入原样是为了日后核查，还是作者当时没顾上整理文件。这两种理解会导致不同的修改决定。前者要求后续改进继续支持追溯，后者则容易让人以为可以顺手删掉暂时用不到的列。

不同位置适合承载不同信息。一个叫“读取温度记录”的函数名，能帮助读代码的人迅速知道这段程序的职责；函数旁的说明可以交代接收什么、返回什么、遇到缺失如何处理；局部注释可以解释一处看起来反常、却有实际原因的做法；入口说明则负责带使用者走完任务。把它们配合起来，比在一个地方塞下全部解释更容易查找。

比如保存结果的代码附近，写“这里保存文件”几乎只是把动作又念了一遍。若写“使用独立结果目录，避免后续绘图覆盖采集记录；相关取舍见数据保留决定”，读代码的人便多得到一条不能直接从保存动作看出的信息。注释仍不必展开整页讨论，因为详细原因已经有固定位置。

Google的文档写作建议区分了命名、注释、接口说明、README与详细文档等层次，并强调它们应提供相应读者需要的信息。可以借这个思路选择放置位置，不必把具体项目机械拆成许多文档。Google：文档实践。

重复放置同一项会变化的事实，还会带来同步困难。假设“温度列名”同时被抄进首页、起步指南、函数说明和一份群公告。后来小叶改了接口，只改了其中两处，读者从不同入口就会得到不同答案。问题不仅是多写了一些字，而是出现了多份看起来都有权决定当前规则的说明。

可以为关键事实确定一个主要位置。输入列名和单位放在输入约定中，起步指南保留必要的最小示例并指向它，详细解释通过链接或明确的章节名称找到。必要的重复仍然可以存在，例如操作旁边再提示一次“秒”，能减少用错的机会；需要控制的是没有维护关系的整段复制。相同内容出现在两处时，小叶应知道改动以后哪些地方需要一起检查。

也不要走到另一端，让每句话都跳转到别的页面。第一次使用的几个必要步骤，最好能在一个连续位置读完。用户每完成一个动作就要打开新的长文，会失去任务线索。入口应足以支持起步，链接用于扩展或深入。文档的组织方式，最终还是要回到读者正在完成的动作。

五、把重要取舍留下来：决策记录回答“当时为什么这样选”

现在回到小叶一个月后的困惑。早期聊天曾讨论“删去不参与绘图的列并写回输入”，当前程序却保留输入原样、另存结果。即使小叶让AI找出保存代码，也还缺少判断下一步怎么改的信息。为此，需要留下决策记录：针对一项重要选择，说明当时的处境、选了什么、为什么，以及接受了什么代价。

在软件工程中，影响结构、接口或重要质量要求的这类记录，常见名称是架构决策记录，简称ADR。Michael Nygard提出的写法包含背景、决定、状态和后果，并保留被后续决定替代的旧记录。我们可以学习这种短记录的思路，用它保存项目里值得让后来者理解的选择。Nygard：记录架构决定。

小叶没有必要给每个按钮颜色都写一篇决定。输入是否保持原样却值得认真留下来。有些实际记录除了时间和温度，还有“实验备注”列，写着记录时的位置或临时发生的情况。备注没有参与这次绘图，日后解释数据时却可能需要。若只保留当前画图用到的两列，再覆盖原文件，温度数值虽然还在，相关背景却可能丢失。以后有人想“把每份输入都整理成两列”，就会碰到这项取舍。记录的篇幅可以短，理由需要具体。

下面是这个案例的一份决定记录片段。它描述R1已经采用的做法。

决定：绘图保留输入，结果另存。
背景： 同一份温度记录可能要重新绘图，也需要结合实验备注核查。当前绘图不用备注，不代表日后解释数据时不需要它。 当前选择： R1只读取所选输入，把图片和处理说明存入指定的新结果目录。
考虑过的另一做法： 先删去不参与绘图的列并写回输入，再生成图片。每份输入看起来都是统一的两列，但原有实验备注会丢失。 接受的代价： 输入保留原有列布局，查阅时仍需辨认时间、温度和其他信息，不能让每份输入看起来都同样简洁。 状态： 已接受，已在R1实现；后续改变保存方式时，需要继续说明怎样保留可追溯的输入。

这份记录给后来者的帮助，并不只是重复“别覆盖”。它把保存方式与一个实际需要连起来：同一份记录可能重新分析，也可能被追问。接手者因此可以评价新的做法。如果未来采用另一种保存机制，能可靠保留各次输入及对应关系，未必还要保持完全相同的目录布局。理由帮助人辨认该保留的能力，具体做法则可以随条件改变。

记录代价也很重要。若小叶只写“此方案安全、清晰、便于追溯”，后来者会看到一份单方面的赞美。保留原有列布局，意味着输入可能没有统一成两列的文件那么容易扫读。使用者如果觉得杂乱，这项困难仍然需要解决。小叶可以考虑在查看界面中突出时间和温度，而保留文件里的完整记录。写清代价，才容易找到同时照顾日常查看与后续核查的改进方向。

替代方案不必越列越多。只要它确实进入过选择，或有助于解释为什么做成现在这样，就值得保留。随手加上几个从未认真考虑、显然不合适的方案，会让记录变长，却不会增加判断依据。也不用把选择包装成客观唯一最优：在当时人员、时间和使用范围下合适，已经是可理解的理由。

最后，记录应尽量靠近做决定的时刻。隔很久再让AI根据代码反推理由，得到的可能是一份讲得通的解释，却未必是当时真正的考虑。代码能为现在的做法提供证据，无法自动证明过去的人为何这样选。若只能事后补写，小叶可以标明哪些理由来自已有讨论，哪些是现在重新评估后确认的，避免替历史编造一个过分完整的故事。

六、当前做法、接受的计划和历史讨论，要让人分得清

记录留下以后，又出现一个问题：它们描述的事情并不都处在同一状态。第一次讨论时的候选方案，后来已经实行的决定，还有正在计划中的新功能，都可能写得很详细。如果读者看不出它们的状态，文档越多，越容易把不同阶段拼成一个从未存在过的产品。

例如，有同学提出，希望比较不同实验相对起点的变化。小叶写下一份提议：“增加选项，把每个温度减去这份记录的起始温度，原始输入仍然保留。”这份提议说明了有可能采用的处理方式，但R1仍然按原温度绘图。读者不能因为看见设计过程完整，就以为工具已经提供了这个选项。

再设一个明确的后续阶段：小叶与使用者讨论后接受了这个功能，准备放进R2，尚未开始实现。这时，“提议中”可以改成“已接受，计划用于R2”。然而，当前使用说明仍要写R1未提供该功能。决定是否接受，回答的是大家准备采用什么；功能是否实现并交付，回答的是用户现在能用到什么。两项状态有关，却不能用其中一项替代另一项。

可以把此时几份材料的作用放在一起看。

这种区分也帮助人理解文档冲突。如果历史讨论说可以覆盖输入，而R1使用说明和已接受的决定说保留输入，首先要看材料各自在描述哪个阶段。知道旧方案未采用，冲突就有了解释。若两份都声称是R1当前规则，一份写保留、一份写覆盖，便不能只挑语气更确定的一份。需要核对当前实现、交付要求和实际行为，查出哪一处应修正。

“以代码为准”也不是所有冲突的最终答案。代码能显示当前实际做了什么，但可能包含缺陷；已经承诺给用户的要求，能显示本应怎样做，却不能证明已经做到。假设当前实现误覆盖了输入，而已接受要求明确保留，这应触发修复和交付判断，不能直接把文档改成“允许覆盖”来消除不一致。文档与实现对齐，要先辨认哪一个才是需要改变的对象。

如果以后R2用新的决定替代某项旧决定，可以在旧记录上注明已被替代，并指向新记录。旧记录仍然解释R1为什么那样运行，当前操作则从R2说明进入。小叶不必把历史全部删除，也不必让使用者在每次画图前读完整部项目史。保留历史与明确当前入口，可以同时做到。

日期有帮助，具体版本和状态同样有帮助。一份昨天整理的历史回顾，并不因为日期最新就成了当前要求。文档标题、适用版本和状态，应让读者在采用其中的建议前，知道这份材料正在说明什么。

七、给AI接手的上下文，也要有对象、依据和状态

人会被散乱文档困住，AI接手任务时也需要可用的项目上下文。这里的上下文，是完成当前任务所需要的背景、约定和证据。把过去全部聊天原样堆进去，有时能补充信息，也会把已放弃的方案、随口猜测和当前要求放在一起，增加判断困难。

小叶这次让AI做的具体任务是“把图标题改得更清楚，显示输入记录名称”。这项修改需要看到R1当前代码、图片输出的位置、输入名称的获取方式，以及有关输出内容的约定。保留输入的决定也值得提供，因为它说明修改不得顺手破坏的现有能力。关于未来起点调整的长讨论，则可以标为尚未实现的计划，在本次不涉及它时保留入口即可。

这不是为了追求最少字数，而是为了让每份材料的身份清楚。小叶可以先说明：“当前交付版本是R1；这次只改图标题。现有输入和保存规则见当前使用说明；保留输入的原因见决定记录。R2起点调整属于已接受但未实现的后续计划。”AI读到这些信息，就有了区分现状、任务和未来计划的依据。

若AI在检查时发现代码与说明不同，还应把差异作为待核实问题返回。例如说明写输出到新目录，代码某条路径却写回输入位置。此时需要指出代码位置、触发条件和涉及的要求，不能悄悄选择一种解释后继续扩大修改。让AI清楚报告证据，比要求它“一定完全理解项目”更可操作。

AI也适合帮助起草文档。它可以从函数、界面文字和文件结构中整理起步说明的候选内容，再由实际操作补齐和纠正。但是“从代码看应该可以运行”“已经实际运行过”“实际运行后输出满足要求”，是三种不同强度的陈述。起草者需要保留这种差别，否则AI写得越顺，读者越难看见哪些部分仍待确认。

设想AI为小叶整理出一句话：“已经在不同电脑上验证，所有同学均可顺利使用。”当前材料只有小叶的一台电脑和一次同学试用，并不支持这个结论。修正时不只是把“所有”改成“多数”，而是回到实际证据：在哪个环境、用哪份输入、完成了什么动作、还有什么未试。没有做过的验证，应明确保留为待办，不能靠措辞变得含蓄就获得事实依据。

同样，AI根据保存代码写出的“采用这种设计是为了满足实验追溯要求”，需要有决定记录或相关讨论支持，才能当作历史理由。如果当前只是合理推测，可以先写成待确认解释。小叶随后核实并补入决定记录，这才把推测转成经过确认的项目知识。

当任务较长，AI会话可能结束，接手者也可能变化。这时，一份接续记录可以留下当前目标、已完成并检查的部分、修改中的部分、已知问题以及下一步入口。它不必复述每条聊天，更有用的是让接手者知道现在站在哪里。例如“标题修改已写入候选版本，但还没核对长文件名的显示”，就比“标题优化完成，效果良好”更能支持下一步工作。

这种记录最终对人和AI都有帮助：人能看清成果是否可用，AI能据此继续具体任务。文档的作用也因此超出“给别人看的一份说明”，成为把零散会话接成持续工作的材料。

八、用一次真实的接手任务检验文档

文档写完，作者觉得顺畅，只能说明它符合作者自己的理解。小叶熟悉项目，看见“选择数据”就知道该选哪份文件、在哪里操作；同学可能连文件类型都没判断出来。要检验起步说明，最直接的方法是让目标读者照着它完成一次任务，并观察在哪里需要额外帮助。

在这个教学情景中，先回看起步说明尚未补齐时的一次试用。小叶把R1交给一位没参与开发的同学，请他使用包内示例生成图片，并说明横纵轴的含义。小叶先不替他寻找按钮，也不主动解释原始温度。这样做的目的，是看说明本身已经支持了哪些动作，而不是让作者的现场讲解把遗漏补完后，再宣布文档没有问题。

假设同学第一次卡在“选择新的结果目录”。说明没有解释该自己新建文件夹，还是由程序创建。同学选了放输入的文件夹，R1拒绝继续。小叶口头教会了他，这次任务能够继续，但文档的问题仍然存在。应该把需要的动作补到那一步：在案例设定的操作方式中，先新建一个空文件夹，再在程序里选中它，用来存放这一轮输出。

同学随后生成了图，却把纵轴解释成“相对起点增加的温度”。说明前面只写了“绘制温度变化”，这个日常表达让他套用了自己原先的预期。小叶需要在结果说明处明确“显示输入中的原有温度，未减去起始温度”，并用示例起点为20摄氏度说明。让同学记住作者现场说过的话，不能代替让下一位使用者在文档里找到依据。

这里检验了两种不同的问题：操作是否可以完成，以及完成后能否解释结果。前者通过不保证后者通过。对于AI工具尤其如此，输出可能已经相当完整，用户却误解了它依据哪些材料、是否经过核实或包含哪些处理。文档验收应选择与实际使用相连的判断，不只是检查文件有没有生成。

修改说明后，可以重新检查受影响的步骤与结果解释。已经听过作者讲解的同学再做一遍，能帮助发现步骤是否仍然卡住，但他的成功也可能借用了刚学到的信息。如果需要了解第一次接手的效果，应再找没有这段背景的人；若暂时没有，只能如实记录这是知情后的复查。不同检查都有价值，不能把它们说成同一种证据。

维护者的接手任务则不同。可以让准备改工具的同学查清：“如果要统一输入布局或调整保存方式，哪项能力必须保留，理由在哪里？”他应能找到数据保留决定，解释完整记录对重新分析与追溯的作用，再评价拟议的改法是否仍保留这些依据。光是搜到“禁止覆盖”四个字，还没有表现出对取舍的理解。

文档中的例子也应与当前版本一起检查。示例文件是否在程序包里，列名是否仍然被接受，按钮名称是否变化，输出目录是否与说明相符，都可以沿同一个起步任务核对。程序内部测试能够通过，并不能保证这些交付材料彼此相接；把文档当作使用路径的一部分，才会发现这类断点。

九、更新文档要跟着变化走，不能只在交稿前整理一次

第一次交接顺利以后，文档仍然会随着项目变化失效。最典型的情况是：小叶改了一个按钮名称，觉得只是小调整，没有碰说明；后来又改了输出位置、加入新选项，使用指南还停在旧版本。等下一位同学来问问题，小叶才发现文章每段单看都很顺，连起来却指向一个已经不存在的操作过程。

所以，更新的触发点可以放在改变发生的时候。改了输入要求，就检查输入说明和示例；改了按钮或操作顺序，就检查起步步骤；改了处理方式，就检查输出解释；改变了重要取舍，就更新相应决定和当前状态。不是每次改代码都必须重写整篇文档，而是判断这次变化会让读者原有的哪项理解失效。

以未来R2真正实现起点调整为例，影响不只是一句“增加了新功能”。说明要告诉使用者怎样选择按原温度绘图或调整起点，输出怎样标明所选方式，示例应该看到什么变化。若使用前面的三条记录，按原温度绘图时仍显示20、21、22摄氏度；选择减去起始温度时，则表示相对起点增加了0、1、2摄氏度。二者回答的是不同的问题，应当在标题或轴的含义中得到区分。

这里明确假设R2已经实现并经过相应检查，才讨论怎样更新交付说明。此前“已接受但未实现”的阶段不能提前写成这些操作已经可用。R2的实现记录、使用说明和实际输出接上以后，新的状态才有依据。这样，文档中的时态变化对应项目中的真实变化，而不是作者觉得计划很快就会完成。

同时，还可能有同学继续使用R1。他们需要的是与R1相配的说明，不能只收到一份R2指南。小叶可以让每份交付包带上对应说明，并在公共入口标出当前推荐版本和旧版本资料的位置。读者由自己手上的版本进入，才不容易拿着新按钮说明寻找旧界面上不存在的选项。

长期有效的办法，通常包括明确维护位置和负责关系。谁修改了输入规则，就在这次修改中检查相关说明；谁准备交付，就确认拿到的是同一套程序、示例和指南。人数少时这些工作都由小叶完成，也可以在一次修改里顺手做完。人数多时才需要进一步划分责任，不必为了写文档先建立一套复杂组织。

对已经失效的当前说明，不能继续挂在显眼入口里等待别人自行辨认。该修正的修正，该转成历史材料的标明历史身份，有重复而无独立价值的可以合并。对有追溯意义的决定和验收记录，则保留其原有上下文。整理文档的目标是让当前使用更清楚，同时仍能查到必要来路。

十、控制记录的分量，把精力用在容易丢失的知识上

讲到这里，可能会觉得需要写的东西很多。实际项目可以从很小的一组材料开始：让人完成第一次使用的入口，解释关键输入输出的约定，再加几项影响后续修改的重要决定。随着真实问题出现，逐步补充。文档的规模应当与软件的使用和协作需要一起生长。

判断一项信息是否值得认真保留，可以看它失去以后会怎样。如果函数已经有清楚名称，代码又直接表现了一个简单动作，再写几段复述可能帮助不大。如果某个看似奇怪的限制来自一个很容易被忘掉的要求，等作者离开以后很难再推断出来，就值得及时记录。越难从现有成果中恢复的理由，越需要在还清楚的时候留下。

还可以看误解后会造成多大返工。例子里，图片颜色选得不合心意，通常容易重新调整；把分钟误当成秒，可能让一份报告的解释整体偏离。两者都属于使用信息，写作上的优先级却不同。首先写清决定结果含义和能否可靠接续的内容，能让有限的整理时间获得更直接的效果。

与其写一段“本系统充分考虑鲁棒性和扩展性”，不如交代一个实际边界：“发现缺失温度时停止，不自动填补；界面显示相应记录位置，使用者先核查原记录。”后者让使用者知道会发生什么，也让修改者知道当前处理选择。等项目真的需要支持补值，再为新的方法和后果增加说明即可。

但简洁也不能成为省略理由的借口。“为安全起见不覆盖”比空泛赞美略好，仍可能让接手者不知道哪种损失需要避免。多写两句关于原始记录、重新分析和来源对应的解释，就能让后续判断发生变化。值得压缩的是同一个结论的重复，不是使结论成立的关系。

这也提醒我们谨慎使用模板。模板可以提醒作者不要忘记状态或后果，但项目很小、决定很简单时，不必为填满每个标题编造内容。相反，若一项取舍涉及几组使用者和明显代价，几行模板也未必够。先讲清实际处境，再决定用多少文字和什么结构承载它。

对大学生来说，最容易开始的练习，是选一个自己已经让AI做出来的小工具，找一位没参与的人尝试使用。把他必须追问、容易误解，以及你过几天就可能忘掉的理由记下来。这个过程会把“应该写文档”变成一个有反馈的行动：写下必要信息，观察它是否减少了猜测，再改进真正失效的部分。

十一、一次完整的交接，应该留下什么

最后回到小叶把R1交给同学的那一刻。此时R1已经按本章设定运行，起点调整仍属于后续计划。小叶不再只交一段宣传式介绍，而是让同学从与R1配套的入口开始：先确认这个工具画原温度记录，再用附带的三条示例走完选择文件、新建并选择空结果目录、生成图片的过程。

同学看见起点为20摄氏度、最后一个记录点位于60秒的图，知道自己得到的是原温度随时间变化的表示。换用自己的分钟记录前，他会先核对单位并保留原记录，准备与秒制约定相符的输入；如果遇到缺失温度，他会回查记录，而不是填一个零只求通过。输入说明和输出解释共同支持了这些动作。

小叶还把保留输入的决定放在接手者能够找到的位置。以后有人准备简化保存方式，可以先理解原始记录对追溯和重新分析的作用，再评价新做法。未采用的覆盖方案和R2计划都标明了状态，不再与R1的当前规则混在一起。需要AI帮忙改标题时，小叶提供当前资料与任务范围，要求把发现的差异和未执行的检查留下来。

这份交接是否完成，最终看同学能否依照材料做出一张含义明确的图，以及后续修改者能否找到必要约定与理由。作者在场时的额外解释，要转回文档里；尚未验证的环境和步骤，也要留在真实状态上。文档由此成为成果的一部分，让这次已经完成的工作，能在下一次使用和修改时继续发挥作用。

练习与参考分析

练习一：这段起步说明缺的是什么

小叶交出一个记录绘图工具，说明只有：“准备好数据后，运行程序，选择合适参数，即可得到结果。”请指出其中最妨碍第一次使用的缺口，并说明你会先补哪些内容。不要仅把这句话扩写得更正式。

参考分析： 这段话把读者还不知道的事情当成了已经完成的准备。“数据”缺少格式、字段和单位；“运行”缺少入口及所需环境；“合适参数”把选择标准交给了初学者；“结果”没有说明保存位置和应有含义。优先补一条完整的最小路径：使用随包示例，从明确入口启动，按必要步骤操作，到指定位置查看输出，并用示例解释正常结果。随后指向完整输入约定，帮助读者换用自己的数据。补充的重点是让动作可执行、结果可判断，不是增加项目优势的介绍。

练习二：列名改对了，为什么图仍然不对

一份记录原本用分钟记时间，三条时间为0、0.5、1，温度为20、21、22摄氏度。小叶的同学把时间列名改成R1要求的time_s，保留数字后导入。程序正常生成图片。他认为没有报错就说明转换成功。这一判断哪里有问题？文档应怎样帮助他发现并修正？

参考分析： R1按秒解释这列数值，改列名没有把原来的分钟数转换成秒数。程序接受了数值形式，却画出与原记录含义不同的时间尺度。正确对应应为0、30、60秒，温度数值仍保持原样。文档应把列名、单位和输出横轴解释放在可以找到的位置，并用一个小示例说明单位改变时数值也要对应调整。使用者可以保留原分钟记录，另存转换后的输入并记录来源。这里需要修正的是输入含义，不能把“能生成文件”当作语义正确的证据，也不必为这个简单转换展开长篇公式。

练习三：决定被接受，就能更新操作指南了吗

小叶与同学同意增加起点调整功能，决定记录已经标为“接受，计划用于R2”。目前交付包仍然是R1，程序尚未实现新功能。AI把首页改成：“勾选起点调整，即可比较相对温度变化。”请判断这项修改，并说明三种材料分别应该怎样处理：决定记录、R1说明、未来功能介绍。

参考分析： AI把已接受的计划写成了当前可执行操作。决定记录可以保留接受状态，但要写明计划版本和尚未实现；R1说明应继续描述现有功能，不能引导用户寻找不存在的选项；未来功能介绍可以解释拟增加的用途，同时明确它属于计划。如果新功能后来实现，还要与实际界面、输出解释和相应检查核对，再更新配套操作指南。错误不在于提前讨论未来，而在于没有让读者区分准备做什么和现在能做什么。

练习四：代码与要求冲突，应当改哪一个

当前输入约定和已接受决定都要求保留所选输入。接手的小叶发现，程序在某条异常处理路径上会写回输入文件。另一位同学建议：“文档应以代码为准，直接把说明改成异常时允许覆盖就一致了。”你会怎样判断？还需要查清什么？

参考分析： 当前代码是行为证据，已接受要求是判断应有行为的依据。发现两者冲突，首先要核实这条路径在什么条件下触发、会写入什么、影响哪些输入，以及保留输入的要求是否仍然有效。若要求仍有效，应修复实现并检查相关行为，不能通过降低说明中的承诺掩盖缺陷。若真实需要已经改变，也应重新评价代价并形成明确决定，再同步实现与文档。单凭“代码存在这种行为”，无法得出“这种行为就是项目应接受的规则”。

练习五：这份决定记录能支持以后修改吗

小叶留下的记录是：“决定采用独立结果目录，因为这样更安全、更规范、更易维护。当前已实现。”请用本章的工具情景补强它，并说明哪些信息比继续增加优点更重要。

参考分析： 应补出具体背景：同一份温度记录可能重新绘图，也可能需要借助实验备注解释数据。当前选择是读取输入并另存图和处理说明，输入各列保持原样。考虑过的删列覆盖方案能把每份输入整理成统一的两列，却会丢失原有备注；保留输入的代价，是查阅时仍需辨认原有列布局。最后说明适用版本和实现状态。这样，未来接手者能评价一种更清楚的查看界面或其他保存机制是否同样保留核查依据，而不只是把当前目录布局当成永久规则。“更安全”需要落到避免什么损失，“易维护”需要落到哪些后续动作，否则只是无法检验的赞美。

练习六：两次试用能够证明什么

同学第一次按照说明操作时，在选择结果目录和解释温度含义两处卡住，小叶现场解释后帮助他完成。小叶修订说明，再请同一位同学操作，这次顺利完成。AI据此写道：“文档已通过首次使用验证，任何新用户都能独立完成。”这句话有哪些超出证据的地方？这两次试用分别还有什么价值？

参考分析： 第一次试用暴露了两个具体缺口，后来的成功借用了作者现场解释，不能说原文已经支持独立完成。第二次试用有助于核查修订后的步骤、文件关系和结果说明是否仍有问题，但参与者已经获得前次知识，不再是没有背景的首次接手者。第一次观察到了初次接手者的困难，完成任务却依赖作者帮助；第二次属于知情后的复查。它们都不足以证明所有新用户能够独立完成，也没有覆盖所有环境。可以如实记录发现、修改及知情后的复查结果；若要进一步了解新手独立起步的效果，再安排新的目标读者尝试。证据的边界不否定已做工作的价值，它帮助小叶决定下一步究竟还需检查什么。