怎么写 Design Doc

写 Design Doc 就像写电影剧本，技术上要正确，情节要合理，上下文要呼应，并且在后面的实现中，所有的设计细节你都能诠释出来。...



工作这么些年，好的 Design Doc，坏的 Design Doc，见过不少，读过不少，也写过不少。

见的多了，就会发现：好的技术设计文档从来就不是写出来的，而是一遍遍 “改” 出来的。因此，除了必须的对技术的把握和理解，一个行之有效的过程就变得非常重要。

当然，不同公司，不同产品，不同规模的 Design 会有很大程度的不同。但是在这个过程中，我觉得下面几个阶段一定是必不可少的。

首先是酝酿阶段。这个阶段，你对产品或者系统需要干什么有一个整体的概念，这也就是设计的需求。根据你组里工程师的资源，以及公司代码库和系统已有的支持和限制，在更加细分的需求上，需要明确哪些是在这个项目中会做的，哪些是暂时不会做的。也就是 Goals 和 Non-goals。这些往往是自上而下的，需要和大组甚至公司的目标以及 Priority 相吻合。通常是可以在第一个版本的 Design 中就锁定的部分，也有特别情况会对部分目标做调整。

一个 Design Doc 的作者，往往最初就在脑海中应该有个大概的想法，整个系统我要做什么、怎么做。即使是不完全的，但是粗略的大纲应该在你的脑海里有个 “可行但不完美” 的蓝图。如果你对于整个系统应该从何下手一筹莫展，那么可能你还没有准备好来做 Design。不如回去多学习，多做调研。

有了脑海里这个雏形的大纲，还是不要急着下笔。约一些两三个人的会议，把你的想法跟你的老板，你的产品经理，你组里相关的工程师，还有相关组的技术和产品……一遍遍描述出来。这时候对象最好一次是一个或者两个。描述中除了把大背景交代清楚，着重在对方比较擅长或者有经验的部分上。不要嫌这是重复劳动或者嫌麻烦。这个过程极其重要，有四个好处：

• 一遍遍跟不同的人描述你的设计，能够帮助你自己理清思路。很多觉得没有问题的地方，当你像讲故事一样跟别人讲出来的时候，可能你就会发现，这个地方似乎衔接不上，或者那个地方似乎不合理。
• 人数少的讨论更易于促进交流。一问一答，最有效的方式利用了对方的时间。别人会更愿意去帮你主动思考，这样很多之前没有想到的问题和关键就会一点点被扒出来。
• 在你扔出一个巨长无比的 Design Doc 前，你其实已经和相关的人做了很多沟通，所以后面的 Review 过程，他们更容易被代入，更明白你想说想做的是什么。
• 多方意见参考，这样收集了更多的需求和限制。这个时候设计在你的脑海里并没有完全成型，这些意见会让你的 Design 更具有整体性，不会漏掉特殊情况的处理，也不会陷入一个基于自己经验的思维定式。

在有了这些讨论和反复思考的基础上，是时候把所有你脑海里的想法记录下来了。第一个版本可以是 “堆砌”，就是把所有脑子里的东西倒出来，确保之前所有的思考和讨论都被包括。第二个版本就开始整理线团一样一遍遍地梳理。如果公司的设计文档有固定模版，那就在这个时候拿这些原材料去填充。更倾向于没有固定模版，这时候你要像写剧本一样，努力把所有的情节和线索用合理的方式一步步展开。让别人通过读文档能够很轻松的跟进你的思路。加一些方便理解、不那么抽象的图表。不用花过多的时间在好不好看上，因为这个阶段的图表往往还要被修改很多次。

如果有可能，同时做一些 Slide，在一些会议上给更多一些人去 present。这时候不是两三个人的会议，也不是文档最终版的演讲，而是一个帮助参会者理解 Design Doc 的手段。所以侧重点在把你其实不太确定的地方跟大家解释清楚，为什么这里你不确定？有哪些选择？各有什么优劣？所以，这些演讲的目的，一方面是在让别人明白你想做什么，为什么做了文档中的那些决定。一方面也是在进一步的调动所有相关人员帮你一起找设计中可能的盲点。

如果没有会议，那就使用基于共享文档的评论功能。把文档分享给大家，大家可以提出疑问、建议、和意见。保证自己很及时的回复评论。另外，建议所有评论的对话不要急着清理，留下这些文档上的讨论，可以帮助别的 reviewer 理解上下文。直到最后所有的讨论有个共同的意见，再把讨论的过程和结果合并到文档中。

上面的过程根据需要可以不断重复，直到所有的设计决策和细节都被相关的人理解和接受。

对于一些大系统的设计，设计的本身也可以被模块化。系统的一部分设计也可以被独立出来，进行更专注的讨论和迭代。比如系统语言和框架的选择、和周边系统的交互方式等等。独立的去走设计流程，再把最后敲定的子 Design 嵌入到整个系统的 Design 中成为一部分。

而一旦敲定了所有 Design 的细节。就要像写文章定稿一样，把整个 Design 做成尽可能完美的文档。这样下来的 Design Doc 很少需要后期进行改动。如果有新人或者外组人想了解这个项目，丢给他/她这个文档就够了。如果有大的改动，一定要把改动传达给所有相关的人。因为大家默认当初定稿的设计就是大家的合约了。

我觉得硅谷工程师文化一个很好的方面，就是每个工程师都不仅是写代码的，而且是整个系统真正的主人（Owner）。在硅谷没有架构师，所有的技术设计会有资深的工程师领头、协调、以及做一些决策，但是系统的细节，每个参与开发的也一定会参与到设计中。很多情况下会负责一个子模块或者功能的设计。这样，一来，所有工程师都能有更多的机会成长和成熟。二来，在开发过程中他/她们清楚的知道整个蓝图，知道一些决定的前因后果，也就更容易写出更可靠的代码和测试。三来，真正调动了所有参与者的思考和积极性，敲定的 Design 是完全透明、所有人反复讨论的结果，极大程度地避免了后期执行中的意见分歧。

题图：from bibliolectors.tumblr.com

    关注 嘀嗒嘀嗒