导语：设计文档是软件工程设计中的重要组成部分。本文根据 Google 及其它公司编写设计文档的经验，并结合实际应用加以完善，系统地介绍设计文档的目的、结构及参考模板，希望推动设计文档在团队中落地，传承并沉淀经验，构建良好的文化氛围。
设计文档是软件工程设计中的重要组成部分，是对一个技术问题的解决方案的系统性描述。设计文档的目的，是阐明设计的总体思想和设计中考虑的权衡点。
作为一名软件工程师，我们的工作本质不仅仅是编写程序代码，而是解决真正的问题。因此，相比最终的程序代码，文字形式的设计文档，在早期能够更加简明扼要地传达信息，便于让读者理解问题，找到解决方案。
除了作为系统设计的最初体现，设计文档在软件工程的开发周期中起到下面重要作用：
通过设计文档，我们可以：
本身撰写设计文档是需要编写成本的。如果问题的解决方案非常清晰，没有明确的取舍，设计文档中基本都是实现描述，则应该省略设计文档而直接实现。换言之，如果编写设计文档的时间主要消耗在“写”而不是在“思考”上，则这个设计文档可省略。当你考虑编写一个设计文档时，想一想以下这几点：
如果以上的问题的答案为“是”，那么设计文档可能是开始你的下一个软件项目的绝佳方法。
在考虑通过用设计文档解决问题，开始着手准备设计文档前，需要厘清设计文档易混淆的三个概念，它们也是创作设计文档的根基。一旦出现偏差，我们认真撰写的文档很有可能完全不可用，在纠正偏差时也会出现大量工作返工，造成资源的浪费。所以，撰写设计文档前需要搞清楚这些前提。
在搞清楚设计文档撰写的三个前提后，就会进入文档的编写阶段。设计文档是非正式的文档，因此他们的内容不会遵循严格的准则，一个首要原则是，针对项目的具体情况可以用相对合理的方式来编写。尽管如此，笔者也参考文献并结合自身经验给出一些建议。
设计文档的写作也是技术写作（Technical Writing），因此同样强调以下三要素：
系统设计及编写设计文档时需要注意的 5 个要点。
在软件设计中，没有任何一个维度有绝对意义上的优劣。每一个设计决定都需要考量很多相违背的因素。例如，可扩展性和效率相背；长期效率和短期收益相背；规模化提升了效率，但降低了灵活性。“高内聚低耦合” 便于迭代，但是会增加短期的开发成本。NoSQL 比 SQL 性能高，但代价是功能的大幅降低。如果一个设计决策看上去没有任何的取舍，往往是因为取舍还没有被识别。在设计时应从取舍视角切入，寻找不同需求间的平衡。
设计所解决的问题往往是复杂而模糊的，因此，解决方案往往是不唯一的。对工程设计，方案的论证通常比方案本身更重要。
做设计取舍时不能忽略时间维度，只设计某个阶段的终态。设计需要考虑以下方面：
设计伊始，界定问题的范围。
一个良好界定的问题是一个良好设计的必要条件。不要迷信设计模型、设计模式、XX 驱动设计。这些是工具，而非法则。不要为了制造问题而解决问题。不要通过复杂的设计来体现工作的难度和深度: 一个困难的问题可能会有一个简单的答案。也不要过于担忧设计被迅速淘汰。保留可扩展性，但不要在未知时浪费精力扩展。
最重要的是要知道如何设计，知道自己在设计什么。列宁·克鲁格效应告诉我们，这未必显然。
I think test-driven design is great. I do that a lot more than I used to do. But you can test all you want and if you don’t know how to approach the problem, you’re not going to get a solution. ——Coders at Work, Peter Norvig
实现代码、系统接口、设计文档，读写比（内容被所有人阅读花费的时间：内容写作花费的时间）是逐步上升的。通常，设计文档供阅读读的时间往往远多于写的时间。因此，编写设计文档时就更多考虑读者的体验而非作者的体验。为提升设计可读性的时间非常值得投资。
设计文档的目的是为了沟通设计，而不是为了自我表达。把精力放在如何清晰、简洁地表达，而非放在文采上
首先先了解你的读者是谁？在良好的文档分享文化下，读者不应该只是你的 TL 以及该设计文档的实施者，你的设计文档实际读者的范围往往大得多。在不确定的时候，经验做法是，假设的读者群体为：公司内部的、有一定工程经验的、但对该系统的上下文只有初步了解的软件工程师。通常，设计文档的范围越大，假定的受众群也会更大。这意味着受众对目标系统的平均了解程度更低，也就意味着设计文档往往需要：
其次，考虑读者喜欢如何阅读？大部分读者不会逐字逐句阅读你的设计文档。大家都很忙。读者通常只会扫描大体结构，然后阅读（或者跳读）自己感兴趣的部分。读者喜欢“故事”。将内容以故事的结构呈现最容易被接受，即使我们并不是需要讲述一个传统的打怪升级的故事。虽然故事内容各有不同，但大部分故事都遵循一些基本的范式。例如，约瑟夫·坎伯 总结提出全世界大部分神话故事都符合“ 英雄之旅 ”-- “启程、启蒙、归程”三幕 -- 这个模式。
对于设计文档/科技论文写作，通用安全的选择是 Writing Science 所介绍的 OCAR 故事结构。
设计文档通常遵循特定的组织结构，我们可以将每一个结构对应到 OCAR 的不同部分，以此讲述故事。
最后，辩证看待设计文档可读性。设计文档可读性 vs. 代码可读性都称作可读性，两者有些共通之处：
| 设计文档 | 代码文档 |
|---|---|
| 说明背景 | 说明上下文 |
| 强调 Why/权衡/其它方案 | 强调 Why |
| 注意事项 | 注意事项 |
| 代码可以清晰表达的内容不需要文档 | 代码可以清晰表达的内容不需要文档 |
用词要简练、准确、直白。
正确使用专业术语。- 合理地使用常见术语可以降低沟通成本。- 不要过多使用过于小众或自创的术语。如果有必要，需要在文中 - 必要时提供对照的英文术语以方便理解。- 避免无上下文的缩略词。
省略程度副词
不管作者意图为何， “非常重要” 和 “重要” 在读者看来大同小异。
使用数据 - 与其说明“该系统的性能提升明显”，不如“该系统的性能提升了 42%”更为可信，也更方便读者做出自己的判断。
忌佶屈聱牙
例如上文，应改为“不要使用过于生僻的词汇，不要过度使用书面语”
千万不要写文言文
“_系统形式问题就是下面这样一个问题：怎样把各种不同的对象种类安排在一个系统中，以使较高的对象种类总能从较低的对象种类构造出来，也就是说前者可还原为后者。为了解决这个问题，我们必须从其相互可还原性来研究各种不同的对象种类。
为此目的，我们要根据所涉及的对象领域的实际科学知识为每一个要考察的对象寻找其基本事实存在的充分而必要的条件的各种可能性。对此我们可采取下面的办法来进行，即要求这门实际科学给出基本事实的一个（确实而常在的）表征_。”Excerpt From: 【德】鲁道夫·卡尔纳普. “世界的逻辑构造.”
段落应该尽量短。通常，一个段落不要超过 8 个完整的句子。每个段落有且仅有一个清晰的主题。每个段落开头应该是主题句，方便读者快速了解段落大意。段落中的每一句话应该与主题紧密相关；否则，它应该另起段落，或者应该删掉。
注意段落的流动。段落句子应该始于一个读者已经熟悉的概念，将新的内容放在句子结尾。这样，读者可以更连贯地理解。
使用 Bullet point 标明无顺序的列表，使用数字序号明确前后顺序。如何正确使用列表不在本文详细展开，会在后续文章介绍，也可参见文末的参考文献。
设计文档不要过长。太多内容堆积在一个文档中会让读者丧失兴趣。
对于一个大型项目来说，10 页（~5000 字）左右是一个合适的长度。当超过这个长度时，可以考虑将问题拆分成子问题分别编写设计文档，并在总体设计文档中链接子设计文档。
对于小问题做增量的改进，考虑使用单页文档(one-pager)。通常这类文档的范围较小，解决问题较简单，目标用户群体仅限于对问题已经有充分了解的内部成员。这时，可以省略背景等内容，而仅使用 目标 -- 方案 两段式论证的结构。
使用统一的字体。用户不会意识到不同的字体代表不同的含义，只会感受到混乱。微软雅黑是安全选择。
不要使用不同颜色来区分内容。不要在文中使用超过三种颜色。可以在标题及分级标题使用标志性的颜色，同时正文使用黑色。
设计文档没有定式。即使如此，笔者参考谷歌设计文档的结构和格式，并结合实际工作经验加以完善。在此提供一个可供新手参考的设计文档模版，您可以使用此文档模板作为思考的基础。通常，无须事无巨细地填写每一部分，不相关的内容直接略过即可。
“我们要解决什么问题？”
用几句话说明该设计文档的关键目的，让读者能够一眼得知自己是否对该设计文档感兴趣。如：“本文描述 Spanner 的顶层设计"
继而，使用 Bullet Points 描述该设计试图达到的重要目标，如：
非目标也可能很重要。非目标并非单纯目标的否定形式，也不是与解决问题无关的其它目标，而是一些可能是读者非预期的、本可作为目标但并没有的目标，如：
设计不是试图达到完美，而是试图达到平衡。显式地声明哪些是目标，哪些是非目标，有助于帮助读者理解下文中设计决策的合理性，同时也有助于日后迭代设计时，检查最初的假设是否仍然成立。
“我们为什么要解决这个问题？”
为设计文档的目标读者提供理解详细设计所需的背景信息。按读者范围来提供背景。见上文关于目标读者的圈定。设计文档应该是“自足的”（self-contained），即应该为读者提供足够的背景知识，使其无需进一步的查阅资料即可理解后文的设计。保持简洁，通常以几段为宜，每段简要介绍即可。如果需要向读者提供进一步的信息，最好只提供链接。警惕知识的诅咒（知识的诅咒（Curse of knowledge）是一种认知偏差，指人在与他人交流的时候，下意识地假设对方拥有理解交流主题所需要的背景知识）
背景通常可以包括：
不要在背景中写你的设计，或对问题的解决思路。
“我们如何解决这个问题？”
用一页描述高层设计。说明系统的主要组成部分，以及一些关键设计决策。应该说明该系统的模块和决策如何满足前文所列出的目标。
本设计文档的评审人应该能够根据该总体设计理解你的设计思路并做出评价。描述应该对一个新加入的、不在该项目工作的腾讯工程师而言是可以理解的。
推荐使用系统关系图描述设计。它可以使读者清晰地了解文中的新系统和已经熟悉的系统间的关系。它也可以包含新系统内部概要的组成模块。
注意：不要只放一个图而不做任何说明，请根据上面小节的要求用文字描述设计思想。
不要在这里描述细节，放在下一章节中；不要在这里描述背景，放在上一章节中。
在这一节中，除了介绍设计方案的细节，还应该包括在产生最终方案过程中，主要的设计思想及权衡（tradeoff）。这一节的结构和内容因设计对象（系统，API，流程等）的不同可以自由决定，可以划分一些小节来更好地组织内容，尽可能以简洁明了的结构阐明整个设计。
不要过多写实现细节。就像我们不推荐添加只是说明"代码做了什么"的注释，我们也不推荐在设计文档中只说明你具体要怎么实现该系统。否则，为什么不直接实现呢？以下内容可能是实现细节例子，不适合在设计文档中讨论：
通常可以包含以下内容（注意，小节的命名可以更改为更清晰体现内容的标题）：
阐明一些复杂模块内部的细节，可以包含一些模块图、流程图来帮助读者理解。可以借助时序图进行展现，如一次调用在各子模块中的运行过程。每个子模块需要说明自己存在的意义。如无必要，勿添模块。如果没有特殊情况（例如该设计文档是为了描述并实现一个核心算法），不要在系统设计加入代码或者伪代码。
如果设计的系统会暴露 API 接口，那么简要地描述一下 API 会帮助读者理解系统的边界。避免将整个接口复制粘贴到文档中，因为在特定编程语言中的接口通常包含一些语言细节而显得冗长，并且有一些细节也会很快变化。着重表现 API 接口跟设计最相关的主要部分即可。
介绍系统依赖的存储设计。该部分内容应该回答以下问题，如果答案并非显而易见：
数据的抽象以及数据间关系的描述至关重要。可以借助 ER 图(Entity Relationshiop) 的方式展现数据关系。
回答上述问题时，尽可能提供数据，将数据作为答案或作为辅助。不要回答“数据规模很大，读写频繁”，而是回答“预计数据规模为 300T， 3M 日读出， 0.3M 日写入， 巅峰 QPS 为 300”。这样才能为下一步的具体数据库造型提供详细的决策依据，并让读者信服。注意：在选型时也应包括可能会造成显著影响的非技术因素，如费用。
避免将所有数据定义（data schema）复制粘贴到文档中，因为 data schema 更偏实现细节。
“我们为什么不用另一种方式解决问题？”
在介绍了最终方案后，可以有一节介绍一下设计过程中考虑过的其他设计方案（Alternatives Considered）、它们各自的优缺点和权衡点、以及导致选择最终方案的原因等。通常，有经验的读者（尤其是方案的审阅者）会很自然地想到一些其他设计方案，如果这里的介绍描述了没有选择这些方案的原因，就避免读者带着疑问看完整个设计再来询问作者。这一节可以体现设计的严谨性和全面性。
如果基础设施的选用需要特殊考量，则应该列出。如果该系统的实现需要对基础设施进行增强或变更，也应该在此讨论。
你的系统如何扩展？横向扩展还是纵向扩展？注意数据存储量和流量都可能会需要扩展。
项目通常需要在设计期即确定对安全性的保证，而难以事后补足。不同于其它部分是可选的，安全部分往往是必需的。即使你的系统不需要考虑安全和隐私，也需要显式地在本章说明为何是不必要的。安全性如何保证？
如何保证数据完整性（Data Integrity）？如何发现存储数据的损坏或丢失？如何恢复？由数据库保证即可，还是需要额外的安全措施？为了数据完整性，需要对稳定性、性能、可复用性、可维护性造成哪些影响？
声明延迟的预期目标。描述预期延迟可能造成的影响，以及相关的应对措施。
是否需要容灾？是否需要过载保护、有损降级、接口熔断、轻重分离？是否需要备份？备份策略是什么？如何修复？在数据丢失和恢复之间会发生什么？
SLA 目标是什么？如果监控？如何保证？
你的外部依赖的可靠性（如 SLA）如何？会对你的系统的可靠性造成何种影响？如果你的外部依赖不可用，会对你的系统造成何种影响？除了服务级的依赖外，不要忘记一些隐含的依赖，如 DNS 服务、时间协议服务、运行集群等。
描述时间及人力安排（如里程碑）。这利于相关人员了解预期，调整工作计划。
未来可能的计划会方便读者更好地理解该设计以及其定位。
我们确实应该把设计限定在当前问题，但是该设计可能是更高层系统所要解决问题的一部分，或者只是阶段性方案。读者可能会对方案的完整性有所疑问，会质疑到底问题是否得到完整解决，甚至会质疑该问题在更高层的系统中是否确实值得解决。“背景（过去）-- 当前方案 -- 未来计划” 三者的结合会为读者提供更好的全景图。
前文强调了要讲故事。以下书目阐述了何谓故事、为什么要讲故事及如何讲故事：
本文由哈喽比特于2年以前收录，如有侵权请联系我们。
文章来源：https://mp.weixin.qq.com/s/XzdeSZZ5MUeewsl3Jy2mEA
京东创始人刘强东和其妻子章泽天最近成为了互联网舆论关注的焦点。有关他们“移民美国”和在美国购买豪宅的传言在互联网上广泛传播。然而，京东官方通过微博发言人发布的消息澄清了这些传言，称这些言论纯属虚假信息和蓄意捏造。
日前，据博主“@超能数码君老周”爆料，国内三大运营商中国移动、中国电信和中国联通预计将集体采购百万台规模的华为Mate60系列手机。
据报道，荷兰半导体设备公司ASML正看到美国对华遏制政策的负面影响。阿斯麦（ASML）CEO彼得·温宁克在一档电视节目中分享了他对中国大陆问题以及该公司面临的出口管制和保护主义的看法。彼得曾在多个场合表达了他对出口管制以及中荷经济关系的担忧。
今年早些时候，抖音悄然上线了一款名为“青桃”的 App，Slogan 为“看见你的热爱”，根据应用介绍可知，“青桃”是一个属于年轻人的兴趣知识视频平台，由抖音官方出品的中长视频关联版本，整体风格有些类似B站。
日前，威马汽车首席数据官梅松林转发了一份“世界各国地区拥车率排行榜”，同时，他发文表示：中国汽车普及率低于非洲国家尼日利亚，每百户家庭仅17户有车。意大利世界排名第一，每十户中九户有车。
近日，一项新的研究发现，维生素 C 和 E 等抗氧化剂会激活一种机制，刺激癌症肿瘤中新血管的生长，帮助它们生长和扩散。
据媒体援引消息人士报道，苹果公司正在测试使用3D打印技术来生产其智能手表的钢质底盘。消息传出后，3D系统一度大涨超10%，不过截至周三收盘，该股涨幅回落至2%以内。
9月2日，坐拥千万粉丝的网红主播“秀才”账号被封禁，在社交媒体平台上引发热议。平台相关负责人表示，“秀才”账号违反平台相关规定，已封禁。据知情人士透露，秀才近期被举报存在违法行为，这可能是他被封禁的部分原因。据悉，“秀才”年龄39岁，是安徽省亳州市蒙城县人，抖音网红，粉丝数量超1200万。他曾被称为“中老年...
9月3日消息，亚马逊的一些股东，包括持有该公司股票的一家养老基金，日前对亚马逊、其创始人贝索斯和其董事会提起诉讼，指控他们在为 Project Kuiper 卫星星座项目购买发射服务时“违反了信义义务”。
据消息，为推广自家应用，苹果现推出了一个名为“Apps by Apple”的网站，展示了苹果为旗下产品（如 iPhone、iPad、Apple Watch、Mac 和 Apple TV）开发的各种应用程序。
特斯拉本周在美国大幅下调Model S和X售价，引发了该公司一些最坚定支持者的不满。知名特斯拉多头、未来基金（Future Fund）管理合伙人加里·布莱克发帖称，降价是一种“短期麻醉剂”，会让潜在客户等待进一步降价。
据外媒9月2日报道，荷兰半导体设备制造商阿斯麦称，尽管荷兰政府颁布的半导体设备出口管制新规9月正式生效，但该公司已获得在2023年底以前向中国运送受限制芯片制造机器的许可。
近日，根据美国证券交易委员会的文件显示，苹果卫星服务提供商 Globalstar 近期向马斯克旗下的 SpaceX 支付 6400 万美元（约 4.65 亿元人民币）。用于在 2023-2025 年期间，发射卫星，进一步扩展苹果 iPhone 系列的 SOS 卫星服务。
据报道，马斯克旗下社交平台𝕏（推特）日前调整了隐私政策，允许 𝕏 使用用户发布的信息来训练其人工智能（AI）模型。新的隐私政策将于 9 月 29 日生效。新政策规定，𝕏可能会使用所收集到的平台信息和公开可用的信息，来帮助训练 𝕏 的机器学习或人工智能模型。
9月2日，荣耀CEO赵明在采访中谈及华为手机回归时表示，替老同事们高兴，觉得手机行业，由于华为的回归，让竞争充满了更多的可能性和更多的魅力，对行业来说也是件好事。
《自然》30日发表的一篇论文报道了一个名为Swift的人工智能（AI）系统，该系统驾驶无人机的能力可在真实世界中一对一冠军赛里战胜人类对手。
近日，非营利组织纽约真菌学会（NYMS）发出警告，表示亚马逊为代表的电商平台上，充斥着各种AI生成的蘑菇觅食科普书籍，其中存在诸多错误。
社交媒体平台𝕏（原推特）新隐私政策提到：“在您同意的情况下，我们可能出于安全、安保和身份识别目的收集和使用您的生物识别信息。”
2023年德国柏林消费电子展上，各大企业都带来了最新的理念和产品，而高端化、本土化的中国产品正在不断吸引欧洲等国际市场的目光。
罗永浩日前在直播中吐槽苹果即将推出的 iPhone 新品，具体内容为：“以我对我‘子公司’的了解，我认为 iPhone 15 跟 iPhone 14 不会有什么区别的，除了序（列）号变了，这个‘不要脸’的东西，这个‘臭厨子’。
