如何写出一份优秀的设计文档

什么是设计文档？

设计文档是一份技术报告，它在各种权衡与约束条件下，勾勒出系统的实现策略。

写设计文档的目标是什么？

可以把设计文档比作数学证明 —— 证明的目标是让读者相信定理成立，而设计文档的目标是让读者相信，在当前情境下这个设计是最优解。

最该被说服的人，其实是作者自己。写设计文档的过程，能给模糊的直觉增加严谨性。很多时候你会发现，原来自己的想法这么草率（往后写代码时，又会发现当初的文档写得有多潦草）。

文档的结构有多重要？

好的设计文档结构，其重要性不亚于代码结构。程序员大多对代码结构有自己的看法，可能都用过 “spaghetti code（ spaghetti 代码，指结构混乱的代码）” 来形容组织糟糕的代码。而多数程序员写的设计文档，若没经过大量练习，也会变成 “spaghetti 文档”。

举个例子，新手程序员常犯的代码组织问题：第一天写代码时，他们会写

plaintext

terminal.print("Hello world")

后来想把文字改成红色，就直接在后面加了一行：

plaintext

terminal.print("Hello world")
terminal.setPrintColor("red")

结果文字没变红，他们还很困惑 —— 其实是没搞懂代码执行顺序：第一行先跑，第二行后跑。他们只是把一堆代码堆在屏幕上，像一锅 “乱炖”，却指望计算机能懂自己的意思。

新手写文档时也会犯一模一样的错，只不过把代码换成了文字。他们把句子和段落堆成一锅 “文字乱炖”，指望读者能自己理清逻辑。

<