怎样根据已交付的改动,口述软件更新说明
先讲用户能看到的变化,再核对上线版本、适用范围和限制,最后整理成发布稿。
更新已经做完,你也能说清改了什么,可更新说明文件还空着。可以先口述用户会注意到的变化,再拿它和实际准备发布的版本对照。上周讨论过的功能,不一定真的进入这次更新。
下面以一款虚构的会议室预订应用为例。前提是你有获准使用的已交付改动清单,也有人能确认实际行为。语音输入帮助你写说明,不会检查代码,也不能替你判断哪些改动已经上线。
挑出用户需要知道的变化
读发布清单,按用户能看到的行为归类。如果错误提示改得更清楚,让用户知道怎样恢复,就值得写入说明。依赖更新可能更适合单独的技术记录,不一定需要公开介绍一整段。项目有特定披露要求时,按项目的发布规定来。
每条公开说明都找一个具体触发场景。比如,用户正要确认,会议室却在片刻之前被别人订走。更新后的行为是保留选中的日期,并请他换个时间。这样比内部工单名“处理预订冲突”更容易懂。
用日常语言讲清变化
在草稿里一次说一条,包含触发条件、结果,以及用户接下来能做什么。刚才那个虚构的冲突修复,可以写成:
确认前会议室被订走时,预订页会保留显示你选中的日期,并请你选择另一个时间。
拿这句话和实际交付的行为对照:日期是真的保持选中,还是仅显示在提示里?所有预订入口都如此,还是只改了网页表单?根据证据收窄说法。没有确认的细节,标成待发布负责人回答的问题,别直接润色成确定结论。
新增选项还要说明在哪里找到、是否需要开启。如果功能仍只向测试组开放,就别让读者到设置里找半天才发现自己没有。
先查适用范围,再修句子
核对版本、平台、开放人群,以及需要做的设置。只在桌面版有的功能,写明桌面版。逐步开放时,区分开始发布和所有人都能用。给日期或宣称问题已修复之前,先确认发布负责人认可这份说明。
留意“一定”“所有”“瞬间”之类的词,它们可能把一项局部改善说得太广。通常换成已经验证的具体场景就足够了。已知限制放在对应功能旁边,扫读的人也能看见。
正文说完以后,再从原始位置复制版本号、设置名称和文档链接。普通句子里一个错字影响阅读,版本号或链接错了却可能让人照着错误的指南操作。
在更新页里读一次
把修订稿移进发布草稿,只读标题,看看用户能不能辨认哪项与自己有关。重要变化放前面,小修复保持简短。点开文档链接;要用截图时,核对它展示的就是这次准备发布的版本。
请一位没写这些代码的同事读完,复述他以为改了什么。如果听起来像一个还不能验证的承诺,发布前就把句子改准。想练习,可以下载 Whisper One 的 Apple 芯片 Mac 版,按首次语音输入指南操作。如果还想记录团队为什么选择这种行为,可以参考项目决策记录指南。
