Google 是如何写设计文档的

小聪拌豆腐

导读： 得多开发者本人十分冷视技术文档的编写，但是又时常埋怨他人的技术文档不完美、品质差、更新不迭时等等…… 这类在开发团队中广泛存在的矛盾乃至曾经演化成为了一个又一个段子。 上面请大家来看Google是如何写设计文档的。谷歌软件工程文明的次要元素之一就是经过设计文档定义软件的设计。
在开始名目编码任务以前，软件零碎或运用顺序的作者会创立这些相对于非正式的文档。设计文档记载了初级完成战略和症结设计决策，而且重点记载了这些决策之间的衡量考量。
作为软件开发工程师，其实咱们的任务实质上不是出产代码，而是解决问题。
非构造化文本，相似设计文档的方式，或许是在名目初期解决问题对比好的工具，由于它易于了解、更简洁，且以比代码更高的档次来沟通问题与计划。
除软件设计的原始文档外，设计文档还完成了软件开发周期中的如下功用：
在初期发现设计问题，而那时变卦的本钱还对比小在组织内环抱设计达成共鸣确保斟酌到穿插畛域的问题将初级工程师的常识扩展到组织中环抱设计决策造成组织记忆的根底在软件设计师的技术组合中充任总结工具设计文档的构造设计文档是非正式文档，因此在内容编写时不会遵守严格的规定。然而，一个首要的准则是，针对详细名目需求用任何最公道的方式编写。
而造成特定的文档构造也一定有它的价值所在。
上下文和规模
这一部份会粗略地向读者引见新零碎是如何构建的以及实际状况如何。
留意，这不是需要文档。请放弃简洁！
咱们的指标是间接让读者理解最新状况，但先前的一些状况能够被揣测或者能链接到具体信息。这个部份应该彻底聚焦于主观配景事实。
指标和 non-goals
这一部份会罗列出零碎指标是甚么，但有时分更首要的是，列出零碎的 non-goals。
留意，non-goals 并非像“零碎不该该解体”这样的负面指标，而是那些本能够公道地成为指标但却明白地选择不作为指标的货色。
一个很好的例子是“ACID 原则”；当设计数据库时，你确定想知道这是一个指标仍是一个非指标。而假如这是一个 non-goals，假如它不会妨碍指标的完成，那你依然能够选择一个提供它的解决计划。
实际设计
这一部份应该从概述开始，而后逐渐扩展至细节部份。



设计文档合适写你在设计软件时所做的各种衡量。把重点放在这些衡量上，而后来产出拥有长时间价值的文档。换句话说，给定上下文（事实）、指标和 non-goals（需要），设计文档能够提供倡议计划，且展现为何某个特定计划最能知足那些指标。
在对比正式的媒介上，编写文档的目的为提供灵敏性，以适量的形式展现手头的问题。因此，关于如何真正地形容设计并无明白的指南。
只管如斯，关于大部份设计文档来讲，一些最好理论和反复话题都颇有鉴戒意义：
零碎语境图
在许多文档中， 零碎语境图都十分有价值。这样一张图将零碎作为更大技术环境的一部份展现，允许读者结合他们曾经相熟的环境进行了解。



零碎上下文语境例子
APIs
假如正在设计的零碎袒露一个 API，那末勾画出这个 API 一般为个好主张。
但是在大少数状况下，人们应该抑制住将正式接口或数据定义复制粘贴到文档中的引诱，由于通常这些定义都很简短，包孕一些不用要的细节，并且很快就会过期。相同，人们应该聚焦于与设计及其衡量相干的部份。
数据存储
存储数据的零碎应该探讨如何及用何种大抵的方式存储数据。和对于 API 的倡议相似，而且理由相反，应该防止复制粘贴残缺的模式定义。相同，要聚焦于与设计及其衡量相干的部份。
代码与伪代码
除了一些形容离奇算法的场景，设计文档应该很少包孕代码或伪代码。在适量的状况下，能够链接到设计完成的原型。
束缚度
影响软件设计和设计文档外形的次要要素之一就是计划空间的束缚度。
极真个一个例子就是“绿地软件名目”，咱们都知道指标，并且解决计划能够是任何最无意义的计划。这样一个文档可能波及面很广，但它还需求疾速定义一组规定，来允许对一组可控的解决计划进行粗疏钻研。
另外一方面，零碎中可能的计划都定义得很好，然而彻底不分明如何将它们组合起来完成指标。这多是一个很难更改的遗留零碎，并且它不是根据你但愿的模样设计的，或者是一个顺序库设计，需求在宿主编程言语的束缚下运转。
在这类状况下，你或许能罗列出相对于容易做的事件，但也需求费些心理将这些事件组合起来，从而完成指标。
有可能存在得多计划，但没有一个是十分好的，因此，这样一个文档应该聚焦于按照一切肯定的衡量点来肯定最好计划。
可供斟酌的备选计划
本节列出了能公道完成相似后果的备选设计。重点应该放在每个设计所做的衡量，以及这些衡量如何致使选择这个设计的抉择，而这恰是这个文档的重要主题。
虽然简单引见终究没有当选中的计划也没有甚么，然而本节会十分明白地展现为何当选中的计划是针对名目指标的最好计划，以及读者可能想知道的，为何其它计划提供的衡量针对指标计划是不太现实的。
穿插关注点
在这里，你的组织能够确保像平安性、隐衷性、可观测性等跨畛域问题被归入斟酌规模。这些通常都是相对于短的部份，解释了设计如何影响这些关注点以及如何解决这些关注点。团队应该将这些关注点规范化。
因为它们的首要性，谷歌名目有一个专门的隐衷设计文档，而且有专门的隐衷和平安审查。虽然这些审查只需求在名目启动时做完，但最佳及早与隐衷与平安团队接触，以确保设计从一开始就将这些考量在内。
关于这些主题的公用文档，核心设计文档固然能够只援用它们，而不是具体引见。
设计文档的长度
设计文档的文字需求足够丰硕凝炼，以便繁忙的人能够真正浏览。
一个较大的名目的文档最好长度是 10-20 页。假如文档过长，最佳将问题合成成多个可控的子问题。
值得一提的是，写一份 1-3 页的“迷你设计文档”也是绝对可行的。这关于矫捷名目中的增量改进或子工作特别有帮忙——你依然能够像处置一个长文档那样处置一切步骤，只需求放弃简洁，且聚焦于一个无限的问题集。
何时不要写设计文档
写设计文档是有开消的。是不是编写设计文档的抉择归根结柢于中心衡量，即环抱设计、文档、初级评审等方面达成共鸣的益处是不是超过创立文档的额定任务担负。这个决策的中心在于设计问题的中心是不是不置可否——这取决于问题的繁杂度或者计划的繁杂度，或者兼而有之。假如设计问题的中心其实不隐约，那末就简直没有价值去编写一份文档。
假如设计文档其实是完成手册，那末这就是一个设计文档不用要的明白目标。假如一个文档根本上在说“咱们是如何完成的”，而不波及衡量、代替计划和决策解释（或者这个计划是如斯显著以致于不需求衡量），那末间接编写实际顺序多是个更好的主张。
最初，创立和审核一个设计文档的开消可能与创立原型和疾速迭代不兼容。但是，大部份软件名目的确存在一些实际已知的问题。遵守矫捷开发办法并非不花时间去解决实际已知问题的借口。
此外，原型构建自身可能就是创立设计文档的一部份。“我试过了，它起作用”是选择一个设计的最好论据之一。
设计文档的生命周期
设计文档的生命周期的几个步骤是：
创立并疾速迭代审核（可能有多轮）完成和迭代保护和学习创立和疾速迭代在这个阶段，咱们也需求编写文档，有时会和一组队友协作编写。
当文档被分享给最理解问题畛域的共事（通常属于同一个团队）时，这个阶段会疾速演化到疾速迭代期，经过他们将问题搞分明以及提供倡议，让文档进入第一个相对于不乱的版本。
虽然你确定会发现工程师乃至团队喜爱版本管制和代码评审工具来创立文档，然而谷歌的大部份设计文档是用 Google Docs 创立的，并且少量使用了它的合作功用。
评审
在评审阶段，设计文档会被分享到除初始作者和亲密合作者以外的更普遍读者。评审能够带来许多价值，但它们也是风险的开消圈套，所以需求理智地处置评审。
评审有多种方式：对比轻量的形式是将文档发送给（对比普遍的）团队列表中，让人们都无机会看一看。探讨次要产生在文档的评论环节。对比重的评审，是正式的设计评审会议，在会议上，作者将文档（一般为一个专门的演示文稿）展现给级别较高的工程师。谷歌的许多团队都会为此按期召散会议，工程师能够报名参预评审。固然，等候这些会议的召散会显著减慢开发进度。工程师能够经过间接追求症结性反馈来减缓这类状况，而不是妨碍更普遍的评审流程。
当谷歌仍是一个对比小的公司时，人们习气于将设计发送到一个中心邮件列表，初级工程师在他们空闲时评审这些设计。这多是一个很好的形式来处置你公司的事件。其中一个益处是，这的确在公司中建设了一种相对于非正式的软件设计文明。然而，当公司范围扩张到一个相对于大的工程团队时，维持集中化的形式变得再也不可行。
评审带来的次要价值是，它们提供了一个时机将组织的综合教训融入到设计中。最为一向的是，评审阶段能够确保将跨畛域的关注点，例如观测性、平安性和隐衷性斟酌在内。评审的次要价值不在于发现问题自身，而是在开发周期的初期就发现问题，此时进行更改的本钱依然相对于较小。
完成和迭代
当事件停顿到确信进一步评审再也不需求对设计进行严重改变时，就能开始完成了。当方案与理想冲突时，不成防止地会泛起一些缺陷、解决不了的需要、三思而行的猜测后果是过错的等状况，而且需求变卦设计。这类状况下，强烈倡议更新设计文档。
个别来讲：假如设计的零碎尚无交付，一定要更新文档。在理论中，咱们人类都不长于更新文档，并且因为其它实际缘故，更改通常被单独放到新文档中。这致使终究形态有点相似美国宪法附带一堆修改案，而不是一份统一的文件。
从原始文档到这些修改文件的链接，关于未来尝试经过设计文档来了解指标零碎的不幸的保护顺序员是十分有用的。
保护和学习
当谷歌工程师面对一个他们从未接触过的零碎时，他们的第一个问题一般为“设计文档在哪里？”。虽然设计文档和其它文档同样，会跟着时间的推移与理想脱节，但它们依然经常是人们理解零碎创立思想的最容易入口。
作为作者，自我回顾并在 1 年或 2 年当前从新浏览你的设计文档。请问下列这些问题：
咱们做对了甚么？咱们做错了甚么？明天你怎么做才会做出不同的抉择？回答这些问题是一个很好的办法，来完成工程师进阶和跟着时间的推移进步软件设计技巧。
论断
设计文档是一个很好的办法，用来在解决软件名目中最难问题的方面进步明晰度，而且达成共鸣。
设计文档节俭了资金，由于它们能够经过事后考察，防止编写无奈完成名目目的的“兔子洞”（ Rabbit holes ，源自《爱丽斯遨游仙境》，指通向未知世界的入口）；设计文档也消耗资金，由于创立和评审设计文档需求时间。
所以，针对你的名目，请理智地选择！
当斟酌编写一个设计文档时，请斟酌下列几点：
你是不是不肯定正确的软件设计，是不是有须要破费后期时间来减少肯定性？与此相干的是，由于初级工程师可能无奈审核每一个次代码变卦，因此请他们参预设计是不是有帮忙？软件设计是不是有不置可否乃至是有争议的，而环抱设计文档在组织上达成共鸣是有价值的？我的团队是不是有时会健忘斟酌设计中的隐衷性、平安性、日志记载或其它的穿插问题？是不是强烈需求文档来对组织中的遗留零碎的设计，以提供高档次的见地？假如你对这些问题中的 3 个及以上的回答均为“是”，那末设计文档多是开始你的下一个软件名目的好办法。
作者：Malte，Vercel首席技术官。此前，Malte是担任谷歌搜寻渲染的首席工程师，以及Search on Laptops, Tablets, 和Desktop的工程总监。