如何准备一份技术文档

Bigno
・大约 11 分钟

该文章的目的是提供一份正确、快速的输出 ERD 的书写规范，尽可能把技术相关的事务说清楚；仅仅介绍你要写什么代码，达到什么样的目的是远远不够，或者说是不规范的，而是当做向别人介绍做这件事的意义以及所有思考。

背景

总结当前需求的背景以及相关文档（context），包括已经进行的相关讨论，例如：已知的问题、历史原因、技术限制。

这里的目的是为了 more context，读者尽可能不需要打开任何链接就能理解设计文档。

目标拆解（Objective）

💡

突出该设计文档旨在解决什么样的目标，并表明对应的优先级。

这里需要注意不要把详细的工作内容列在这里，比如：

  • ❌：和 Server 一起排查接口为什么没有 XX 字段以及对应的 Error Code 和 Error Message；

  • ✅：优化接口监控和错误处理，使用异步调用降低 API 加载时长；

比较规范的目标拆解：

  • [P0] 重构 XX 组件/模块，提升代码的可阅读性、可维护性、可复用性；

  • [P0] 升级 XX SDK 至 X.Y.Z 版本，更新 XX 模块避免升级带来的 break change；

  • [P0] 新增 XX 组件/模块，分解 XX 组件至更小力度，提升组件的可阅读性、可维护性、可复用性；

  • [P0] 提升 XX 组件/模块的渲染性能，解决重复渲染/请求的问题；

  • [P0] 数据获取

    • 新增 XX 接口，修复 XX 接口问题；

    • 优化接口监控和错误处理；

    • 使用异步调用降低 API 加载时长；

    • 完善 API 请求和响应的类型校验；

  • [P0] 完善 XX 组件/模块的关键测试用例；

  • [P1] 完善 XX 组件/模块的 TypeScript 类型；

  • [P1] 修复 XX 函数/三方 API 的滥用行为，提升 XX 性能；

  • [P2] 清理无用代码

  • [P2] 将 Class 组件转换至函数组件；

  • [P2] 清理无用代码和文件。

至此，可以初步看出你在这一次需求或者技术改造中需要做的大致事项，不需要太具体，可以单做最后的目标来写；

同时，这也会是你在开发（或者项目管理）过程中的一份 Checklist，并且因为你已经标明优先级，在面对遇到的突发事件可以快速调整关注点。

收益指标（Metrics）

💡

定义哪些指标可以作为收益的标准，以及如何衡量指标是否达到预期；业务指标和工程指标都应该包括在内。

除了 PRD 上的直观收益（业务收益），如 DAU、点击率、渗透率等关键指标的增长；

还需要包括工程上的收益，如 FCP 等指标的时间、测试覆盖率、请求时间、加载时间等等。

技术选型（Design Overview）

💡

包括技术栈选择，不同技术栈、第三方库的优劣分析。

好的做法：先用 1~2 句话「介绍」目标技术/工具，然后概括优劣，而不是直接表达「XX 技术/工具更好用」；

概述后，再使用「表格」（table）或者「列表」（list）去逐个分析各自的优点（Pros）和缺点（Cons）；关于各自的优缺点最好有一个小的 DEMO 或者录屏来表达当前的使用场景。

技术细节（Design Details）

在技术细节中，我们要做的是对前面的「目标拆解」中提到的每个步骤，提供具体的做法；

模块划分

这里的每个模块就是我们要做的具体的事，包括每个模块的标题都需要言简意赅的说明是「哪一件事」而不是「哪一类事」，然后再加上一两句话的解释；

比如我们现在要做的是组件/模块拆分，我们可以需要划出一个 Section 专门说这件事，每个部分的标题就是具体的模块如「XX 组件拆分/优化」，然后加上一两句话解释这是什么组件、做什么用。

这里关键的地方在于，标题不能太细节，细到你要改什么代码或者用什么新的第三方库，也不能太宽泛，宽到优化 XX 性能；

而是需要让人大概知道你要对什么东西做什么事，就想上面说的「XX 组件拆分/优化」，具体的概述和细节可以放到 Section 中，这个度需要自行衡量。

技术细节

在技术的细节介绍中，我们需要贴上具体的步骤、关键的代码、必要的截图、遵循的原则等，唯一目的就是方便读者理解你会怎么做。

所以在书写过程中应该注重：这是个什么问题？解决方案是什么？产出是什么？

在书写过程中需要注意的地方：

  • 示例需要完整，不要只截取代码的一部分，或者展示的一部分；展示所有必要的上下文信息，如接口需要展示接口地址、调用方式（method）、请求及返回结果结构体等；

  • 提供必要的解释，读者或许不知道其中具体的细节；比如列出了文件目录结构，需要介绍关键的目录结构路径，关键文件的介绍；或者你在文中提到了某个数据结构，就需要附带说明这个数据结构的作用，而不是仅仅提供一个变量名及其字段；或者你在做一个复杂流程的改造，那么尽可能梳理一下现有流程以便读者理解整体流程；

  • 按照信息的重要性排序，比如扩展阅读可以放到尾部的「附录」，读者一般不会在刚开始阅读的时候就去读扩展阅读；

  • 简化或移除不重要的信息，你展示的所有信息都是为了辅助说明你要做的事，比如一上来就贴一大段代码，包含了很多不重要的逻辑处理，容易让读者困惑，如果必要的话就简化代码并说明代码的作用，如果不需要这段内容也能理解你在做什么那就果断的删掉吧；

  • 用数据说话，找到你要观测的指标，在优化或者改造前获取对应的指标数据，方便后优化/改造后的数据进行对比；

测试计划及回滚方案（Testing and Rollout Plan）

测试计划：指引其他 RD 或者 QA 去测试对应的功能更新；

回滚方案：给自己留条后路。

引用（Reference）

最好可以分类列出文章中的所有引用，方便用户进行细节阅读。

其他可选内容

  • 术语表（Glossary）：解释接下来在文档中会出现的专业名词或简称；

  • 附录（Appendix）：文章用的扩展阅读都可以放到这里，一般放在页尾；

最后

不管是业务开发、技术需求，还是项目推进管理，文档的书写都需要做到认真严谨，让人容易理解并信服，愿大家都能更上一层楼 🥳