Google 的设计文档
谷歌软件工程文化中一个关键要素是使用设计文档来定义软件设计。这些文档相对非正式,由软件系统或应用程序的主要作者在开始编码项目之前创建。设计文档记录了高层次的实现策略和关键设计决策,特别强调在这些决策过程中考虑的权衡。
作为软件工程师,我们的工作不仅仅是编写代码,而是解决问题。在项目生命周期的早期阶段,非结构化文本(如设计文档)可能是解决问题的更好工具,因为它可能更简洁、更易于理解,并且能够在更高层次上传达问题和解决方案,而不仅仅是代码。
除了对软件设计进行原始文档记录外,设计文档在软件开发生命周期中还履行以下功能:
- 在进行更改时,尽早识别设计问题成本较低。
- 在组织内达成设计共识。
- 确保考虑跨切面关注点。
- 将资深工程师的知识扩展到整个组织。
- 形成组织关于设计决策的记忆基础。
- 作为软件设计师技术作品集中的摘要文档。
设计文档的构成
设计文档是非正式文档,因此其内容不遵循严格的规范。第一条规则是:以最适合特定项目的方式撰写。
尽管如此,一种特定的结构已被证明非常有用。
背景与范围
本节为读者提供新系统所处环境的粗略概述,以及实际构建的内容。这不是需求文档。保持简洁!目标是让读者快速了解情况,但可以假设读者具备一些先验知识,详细信息可通过链接获取。本节应完全聚焦于客观背景事实。
目标与非目标
简要列出系统目标的要点,有时更重要的是明确非目标。需注意,非目标并非对目标的否定(如“系统不应崩溃”),而是那些本可成为目标但被明确排除的事项。一个很好的例子是“ACID合规性”;在设计数据库时,你肯定想知道这是目标还是非目标。如果它是非目标,你可能仍然会选择提供该功能的解决方案,只要它不会引入阻碍实现目标的权衡。
实际设计
本节应先概述,再详细展开。
设计文档是记录你在设计软件时做出的权衡取舍的地方。专注于这些权衡取舍,以产出具有长期价值的有用文档。也就是说,在给定上下文(事实)、目标和非目标(需求)的情况下,设计文档是提出解决方案并说明为何特定解决方案最能满足这些目标的地方。
撰写文档而非使用更正式的媒介的目的是为了提供灵活性,以便以适当的方式表达当前的问题集。正因如此,没有明确的指导说明如何实际描述设计。
尽管如此,一些最佳实践和常见主题在大量设计文档中具有普遍适用性:
系统上下文图
在许多文档中,系统上下文图 非常有用。此类图表展示系统作为更大技术环境的一部分,使读者能够基于其已熟悉的环境背景理解新设计。
系统上下文图示例。
API
如果正在设计的系统暴露了一个 API,那么绘制该 API 的草图通常是个好主意。然而,在大多数情况下,应抵制将正式的接口或数据定义直接复制粘贴到文档中的诱惑,因为这些定义往往冗长、包含不必要的细节且很快就会过时。相反,应专注于与设计及其权衡相关的部分。
数据存储
存储数据的系统应讨论数据存储的方式及大致形式。与API相关的建议类似,出于相同原因,应避免直接复制粘贴完整的模式定义。相反,应重点关注与设计及其权衡相关的部分。
代码与伪代码
设计文档通常不应包含代码或伪代码,除非在描述新型算法时。如有必要,可提供原型链接以展示设计方案的可实现性。
约束程度
影响软件设计形态(进而影响设计文档)的主要因素之一,是解决方案空间的约束程度。
一端是“绿地软件项目”,此时我们仅知晓目标,解决方案可自由选择最合适的方案。此类文档可能涵盖广泛,但需迅速定义一套规则,以便聚焦于可管理的解决方案集。
另一端是解决方案已非常明确的系统,但如何将这些解决方案组合以实现目标并不明显。这可能是难以更改的遗留系统,或未按预期设计的功能,或是受宿主编程语言约束的库设计。
在这种情况下,你可能能够相对容易地列出所有可行的方案,但需要创造性地将这些方案组合起来以实现目标。可能存在多个解决方案,且没有一个是真正理想的,因此此类文档应重点在于在已识别权衡中选择最佳方案。
考虑的替代方案
本节列出可合理实现类似结果的替代设计方案。重点应放在各设计方案所做的权衡以及这些权衡如何导致选择本文档主要讨论的设计方案。
虽然可以简要提及未被选中的解决方案,但本节是至关重要的部分,因为它明确说明了为何在项目目标下所选方案是最佳选择,以及其他方案(读者可能感兴趣的)如何引入与目标不符的权衡。
跨领域关注点
这是组织确保某些跨领域关注点(如安全、隐私和可观察性)始终被考虑的环节。这些通常是相对简短的章节,解释设计如何影响关注点以及如何解决该关注点。团队应在自身案例中标准化这些关注点的内容。
由于其重要性,Google 项目必须具备专门的隐私设计文档,且有专门的隐私与安全审查流程。尽管这些审查仅需在项目上线时完成,但最佳实践是尽早与隐私与安全团队合作,确保设计从一开始就考虑这些因素。若存在专门针对这些主题的文档,中央设计文档当然可以引用这些文档而非重复详细说明。
设计文档的长度
设计文档应足够详细,但也要足够简短,以便忙碌的人能够阅读。对于大型项目,理想的长度似乎在10到20页左右。如果超过这个范围,可能需要将问题分解为更易于管理的子问题。值得注意的是,完全可以撰写1到3页的“迷你设计文档”。这在敏捷项目中的增量改进或子任务中尤为有用——你仍然需要完成与较长文档相同的步骤,只是要保持内容简洁,并专注于有限的问题集。
何时不应编写设计文档。
编写设计文档是一项额外的工作。是否编写设计文档的决策,本质上取决于权衡组织在设计共识、文档记录、高层审核等方面的收益是否大于编写文档的额外工作量。这一决策的核心在于,设计问题的解决方案是否存在模糊性——无论是由于问题本身的复杂性、解决方案的复杂性,还是两者兼而有之。如果不存在模糊性,那么编写文档的过程便价值不大。
一个明确的信号表明文档可能不需要存在,就是那些实际上是“实现手册”的设计文档。如果文档基本上只是说“这就是我们打算如何实现它”,而没有探讨权衡、替代方案以及解释决策过程(或者如果解决方案如此显而易见以至于不存在权衡),那么直接编写实际程序可能是一个更好的选择。
最后,创建和审查设计文档的开销可能与原型设计和快速迭代不相容。然而,大多数软件项目确实存在一组“已知问题”。采用敏捷方法论不能成为不花时间解决已知问题的借口。此外,原型设计本身可能是设计文档创建的一部分。“我试了一下,它有效”是选择设计方案的最佳论据之一。
设计文档生命周期
设计文档生命周期的步骤包括:
- 创建与快速迭代
- 审核(可能分多轮进行)
- 实施与迭代
- 维护与学习
创建与快速迭代
你撰写文档。有时会与多位共同作者合作。
此阶段迅速演变为快速迭代阶段,文档将与最了解问题领域(通常属于同一团队)的同事共享,通过他们的澄清问题和建议,推动文档达到第一个相对稳定的版本。
虽然确实有工程师甚至团队更倾向于使用版本控制和代码审查工具进行文档创建,但谷歌绝大多数设计文档都是在Google Docs中创建的,并充分利用其协作功能。
审核
在审核阶段,设计文档会分享给比原始作者和紧密合作者更广泛的受众。审核可以带来很大价值,但也是一个危险的冗余陷阱,因此要谨慎对待。
审核可以采取多种形式:较轻量级的版本是将文档发送给(更广泛的)团队列表,让大家有机会查看。讨论主要在文档中的评论线程中进行。在审核的另一端,是正式的设计审核会议,作者会向通常由高级工程师组成的听众展示文档(通常通过专门的演示文稿)。谷歌的许多团队都会安排定期的此类会议,工程师可以报名参加审核。当然,等待此类会议的举行可能会显著延缓开发进程。工程师可以通过直接寻求最关键的反馈,而非因广泛审核而阻碍进展来缓解这一问题。
当谷歌还是小型公司时,通常会将设计方案发送至单一中央邮件列表,由高级工程师在空闲时进行审查。这可能非常适合贵公司的处理方式。其优势在于确立了公司范围内相对统一的软件设计文化。但随着工程团队规模大幅扩张,维持集中化审查模式变得不可行。
此类审查的主要价值在于,它为组织集体经验融入设计提供了机会。最重要的是,确保设计考虑跨领域关注点(如可观察性、安全性和隐私性)是在审查阶段可以确保的。审查的主要价值并非在于发现问题本身,而在于这些问题在开发生命周期早期被发现,此时进行修改的成本相对较低。
实现与迭代
当事情进展到足以确信进一步审查不太可能需要对设计进行重大修改时,就该开始实施了。当计划与现实发生冲突时,不可避免地会出现缺陷、未解决的需求或被证明是错误的推测,这些都需要修改设计。在这种情况下,强烈建议更新设计文档。作为经验法则:如果设计系统尚未发布,那么一定要更新文档。实际上,人类在更新文档方面做得并不好,而且出于其他实际原因,更改通常会被孤立到新的文档中。这最终导致了一种更类似于美国宪法附带大量修正案的状态,而非一份一致的文档。从原始文档链接到这些修正案对未来维护程序员通过设计文档考古来理解目标系统将大有帮助。
维护与学习
当谷歌工程师面对一个他们之前未接触过的系统时,他们通常会首先问:“设计文档在哪里?”尽管设计文档,如同所有文档一样,随着时间推移往往会与现实脱节,但它们仍然常常是了解系统创建过程中指导思想的最便捷入口。
作为作者,请善待自己,在一年或两年后重新阅读自己的设计文档。你做对了什么?做错了什么?如果今天重新决策,你会如何选择?回答这些问题是提升工程能力、逐步改善软件设计技能的绝佳方式。
结论
设计文档是解决软件项目中最棘手问题时,实现清晰沟通和达成共识的有效工具。它们能节省成本,因为通过前期调研可以避免陷入无法实现项目目标的编码死胡同;但它们也需要成本,因为创建和审核需要时间。因此,请根据项目需求谨慎选择!
在考虑编写设计文档时,请思考以下几点:
- 您对正确的软件设计是否存在疑虑,是否值得提前投入时间以获得确定性?
- 相关地,是否需要让高级工程师参与设计(尽管他们可能无法审查每个代码更改)?
- 软件设计是否存在模糊或争议,以至于达成组织共识具有价值?
- 我的团队在设计过程中是否经常忽略隐私、安全、日志记录或其他跨领域关注点?
- 组织内是否存在对提供遗留系统设计高层次洞察的文档的强烈需求?
如果您对上述问题中有3个或更多回答是肯定的,那么设计文档可能是启动下一个软件项目的绝佳方法。
本文文字及图片出自 Design Docs at Google
设计文档是我最喜欢软件工程的一部分。如果代码是砖瓦和水泥,那么这些文档就是蓝图。
我知道这有点争议,但我们的工作不仅仅是写代码。在组织中导航并在大多数团队/技术之间达成共识是其中很大一部分。
设计文档是一种在编写数千行代码之前就解决所有这些问题的途径。审查过程也会带来与代码审查截然不同的反馈。
> 在组织中导航并在大多数团队/技术之间达成共识是其中重要的一部分
我认为这是设计文档的主要优势——它们是扩展你工程影响力的方式,超越你个人的输出。如果你编写一个设计,而你的设计允许你和另外三名工程师协调努力,那么你的工程输出现在是“我协调了一个团队来构建一些我们任何人都无法单独编写的东西”。
这与你的下一点完美契合——尽早发现阻碍因素对协调多个实体至关重要。项目计划通常假设每个任务都能成功,但可能会有额外任务被添加。如果某个任务无法完成/需要重新设计某物/等,这将突然使N名工程师的工作陷入停滞。越早成功将工作分解为一系列已知未知和实施任务,项目整体进展就越顺利。
> … 尽早发现阻碍因素对于协调多个实体至关重要。
我认为对我来说,挑战一直在于“发现阻碍因素”这一环节意味着需要构建一个或多个小型原型来验证依赖项的能力、检查可行性等。因此,这些原型的构建通常在设计文档编写之前或与之并行进行,但随后在某个阶段会被暂停,以便完成并审查设计文档,然后在真正开始实施时再继续。
但在此暂停需要自律,因为理想情况下,暂停应在所有主要障碍已被清除且最想立即加速推进、将原型整合到项目中的时刻发生。
与已看到原型并可能认为项目已完成90%的利益相关者明确预期也至关重要,事实上将原型打造成生产就绪状态仍需完成剩余90%的工作。
>如果代码是砖瓦和水泥,那么这些文档就是蓝图。
这个比喻很快就会破裂。设计文档不够具体,无法与蓝图相提并论。
你可以将一组蓝图交给三家不同的建筑公司,最终得到的是基本相同的建筑。试着将设计文档交给三家不同的开发团队,看看会发生什么。
问题在于,要达到那种具体程度,只能通过代码实现。
设计文档更接近城市规划师会产出的内容,而非建筑师或土木工程师会产出的内容,因此应相应对待。
我的意思是,你说得对……但类比的目的是不是完美,而是作为一个粗略的思维模型,快速表达一个概念。我觉得没问题。
不同工作需要不同抽象层次,设计文档正是为软件工程师履行这一角色。
这确实没错,但如果类比过于不完美,就无法准确表达概念。
糟糕的类比就像一把漏水的螺丝刀。
是的,模型即使不完美也可能有用。但这个模型不仅过于脱离实际而无法实用,反而弊大于利。当人们(尤其是管理者)开始将设计文档视为蓝图、软件架构师视为建筑师、开发人员视为建造者时,这种预期本身就极其危险。
模型总是存在缺陷。
类比是解释的蓝图。
这是应该在学校就教给人们的东西。 “蓝图类比”已经固化了这样一种观念:存在一个 “设计阶段 ”和一个 “构建阶段 ”,而且这些阶段往往是相互独立的。
在软件领域,这种观点再错误不过了。在软件中,设计就是代码。编译器/解释器才是系统的构建过程。
> 在软件领域,设计就是代码。编译器/解释器才是系统的构建过程。
我认为这种观点过于教条。是的,没错,但当我设计软件时,我描述的是其高层次特性,更像是描述一本书的故事情节,而非书中具体的文字和角色之间的对话。
我认为设计有许多层次,代码是最后的层次。
你的设计看起来可能非常出色,但当你实际编写代码时,它可能存在严重缺陷。土木工程师使用的设计(蓝图)基于多年的实践经验,这些经验被纳入工程规范中,有时甚至可以追溯到数千年前。设计中的关键问题,如力之间的相互作用方式,可以通过数学分析来解决。对于类似UML的图表和书面“规格说明”,我们唯一能做的检查是同行评审。这完全不同。
如果设计就是代码,那么什么是bug?无论是否写下来,都存在一个独立的模型,规定代码必须做什么。那就是设计。
当设计存在缺陷时会发生什么?是否存在一个更高层次的设计,其顶端是一个人类无法知晓的理想设计?乌龟一直往下。
每个利益相关者心中都有不同的“设计”,除非你真正具体化,否则不存在设计,只有一个模糊、不完整的需求列表。如果你试图具体到可以复现的程度——你就是在写代码。
这并不是说设计文档毫无价值,只是它们永远无法具体到像蓝图那样作为实际可复现的设计。这样看待它们是有害的。
确实,它们不可复现。还有其他明显的区别吗?
可重复性只是缺乏具体性的副作用,这是主要差异,也是我批评的全部要点。设计文档没有提供足够的信息来实际构建你想要构建的东西。
我的意思是,除了无法两次构建相同的东西外,还有其他实际后果吗?
假设你认为设计文档提供了构建软件所需的所有信息,无需进一步设计工作。
围绕这一假设构建软件开发方法论。现在去除这一假设,想想对于一个在开始实施设计文档后才意识到假设错误的团队,实际后果会是什么。
想象一下,如果你雇佣一家建筑公司来绘制房屋的蓝图,然后在房屋建造过程中发现蓝图中的假设与实际可建造的内容严重不符。
如果管理层在过程中了解设计文档和前期设计的局限性,对所有相关人员来说会好得多。
要了解实际问题的具体例子,可以参考过去30年间关于迭代设计与 upfront 大设计方法论的争论历史。
我认为他们将“设计”比作建筑的蓝图。我完全同意他们的观点,即在这种意义上,代码才是蓝图,而非建筑本身。程序的执行相当于实际施工:建筑师(计算机)根据蓝图(代码)建造建筑物(执行程序)。计算机的优势在于,“建筑物”(执行)部分本质上是免费的且可无限复制。但“蓝图”(代码)的创建仍需大量人力。
设计文档的正确类比其实是项目的高层级愿景定义。工程师不会一到现场就开始绘制蓝图;而是先由一人或多人提出建筑项目的目的和概念,探讨实现方法,评估权衡,达成共识后,再与工程师合作开始创建并迭代蓝图。这一愿景阶段正是设计文档的适用场景。
这些内容在Fowler的《新方法论》中得到了极好的阐述。
https://martinfowler.com/articles/newMethodology.html
你住过有设计缺陷的房子吗?
我第一套公寓的卫生间门因马桶而无法完全打开。这在蓝图上是正确的。
没错,这是验证问题,正如NASA所称:
https://en.wikipedia.org/wiki/Verification_and_validation
不,那是需求。
“设计即代码”这一观点并不意味着设计与构建在软件中是不可分割的。
从这个理念中需要理解的是,设计文档并非刻在石板上的法律,而是一个可变的基础。它确保你的设计在高层次上保持一致。如果你最终与现实发生冲突,且设计无法实现,你可以回到设计文档并根据需要进行调整。
简而言之,设计文档应是一个活文档。
我认为你在这里讨论的是“意图文档”,而非设计文档。设计关乎“规划”,这意味着你需要详细定义各项内容,包括步骤和技术。而意图则关乎你希望实现的目标。两者截然不同。
设计文档确实是计划。但如果计划在面对现实时行不通,你就需要修改计划,因此也需要修改设计文档。
设计是一个大纲、草图或计划。因此它不指定细节的程度。
> 设计就是代码。这就是为什么软件开发绝不能被视为工程学。架构很重要,在施工阶段,设计会发生变化和修订,这些变化会被记录并正式审查。
在软件中,如果代码是“设计”,那么计算机科学应该优先达成共识,采用一种标准化的设计表示形式(如UML),该表示形式可以由编译器/解释器生成,并配合代码覆盖率和静态分析。
问题在于,尚未将设计和实现的正式严谨性融入代码,以证明正确性,同时缺乏适用于领域状态的数据结构和算法。此外,还需要易于理解和使用的构建和测试工具。
基础设施已具备,包括CI/CD、GitHub/GitLab、Team Foundation、CVS代码库,以及类似GPT-3的继任者来完成分析代码以确定与现有代码库和开发冲刺分支相比的最佳实现模式的繁重工作。
即使对于极具经验和能力的开发者而言,编译代码或“构建”代码也可能是一场赌博。
一些值得思考的问题。
代码即设计,而设计揭示了代码的好坏。GoF设计模式是基于良好代码编写而设计的。反模式(瑞士军刀是我最喜欢的)则是糟糕的代码编写。
如果曾经参与过根据蓝图制造产品的工程,这个类比其实很有道理。
如果你将一份复杂的蓝图交给三家随机的建筑公司,从远处看,结果几乎相同,但仔细观察,项目过程中很多细节都会发生变化。
这就是为什么工程师需要在一定间隔对项目进行检查并执行质量控制。
在某种程度上,确实会存在差异,但对于最终用户来说,除非出现问题,否则他们无法察觉太多差异。
房屋的蓝图要比软件项目的设计文档容易复制得多。
如果你将设计文档交给3家不同的开发公司,最终结果会大相径庭。
>工程师之所以需要定期检查项目并进行质量检测,是有原因的。
确实,蓝图仍是一种模型,因此存在一定的解释空间。但你所说的差异主要源于人们会偷工减料、不遵循规范,而非规范本身不存在。
我完全同意。最好的软件文档就是一个实际编写良好的软件模块加上测试,解释其功能。
别忘了注释。
一段写得好的代码只会告诉你它做什么,一套好的测试会教你如何使用它,但只有自然语言文档——无论是注释还是独立文档——才会解释代码为何存在以及为何如此设计。
(至于“自文档化代码”,除非你的很多函数名称中都包含“因为”这个词,否则代码其实并不算自文档化。)
总结:什么 -> 命名规范 为什么 -> 注释 如何 -> 测试
我希望这一点能被更广泛地分享和理解
> 我知道这相当有争议,但我们的工作不仅仅是编写代码。
我不知道这是否真的有争议,但我不想在这样有争议的地方工作。
我认为——根据我的经验——在传统的IT组织中,这种情况绝对不成立。项目管理办公室(PMO)负责业务需求,而几乎没有时间用于创建详细的设计文档(DDs)。你基本上只能从产品需求文档(PRD)直接跳到编写代码……如果你有幸拥有内部软件质量保证(SQA)团队和相对有效的持续集成/持续交付(CI/CD)流程,你只能依赖利益相关者的快速反馈来验证开发人员所做的假设和推测是否正确。由于在许多情况下,业务所有者从未真正考虑过许多边界情况(愚蠢的基本例子:前公司要求所有国际差旅申请必须获得首席财务官批准。工具是按照这一逻辑开发的。没有人考虑过当首席财务官因任何原因无法联系时如何处理,因此当首席财务官第一次休假时,这导致了各种愚蠢的混乱,同时手动流程被创建。),灵活的逻辑路径并未设计到工作流应用程序中。同样,对于报告/商业智能工具,高管希望从数据中获取的答案与最终生成数据的业务流程之间常常存在差距。因此,几乎所有报告都存在缺陷,但除非你足够接近这些流程,否则无法解释这些缺陷,这可能导致缺乏信息支撑的业务决策。CRUD应用程序也是如此,表单验证规则可能因无谓的原因变得异常复杂,导致输入的数据无法使用。
抱歉说了这么多。我喜欢设计文档,但更欣赏那些注重简单性和易用性的软件工程文化,而不是试图满足所有人的需求(更糟糕的是,成为某个高管的个人项目,而这位高管每季度都会改变对系统运作方式的看法)。
是的,这听起来像是带着很多包袱,其中一些术语我甚至不熟悉(SQA、DD?)。
目前,我们从产品经理那里获取高层次的功能设计文档,并将其转化为服务。在这之间的一切,包括资源、开发、运维,都由一个团队负责,团队中每个人的头衔都是软件开发工程师(SDE)。这给我们带来了很多沟通、写作和设计的工作,但我并不抱怨。
我认为这种误解的产生是因为在职业生涯的早期,人们对工作的期望更多地集中在编写代码来实现他人定义的愿景上。从这一点来看,很容易认为编写代码是工作中最重要的部分。但实际上,情况恰恰相反,更重要的非编码部分工作被委托给更有经验的人(往往让他们感到沮丧,因为编写代码要有趣得多)。
随着我经验的增长,我注意到,刚开始时,项目经理或高级工程师会给我分配任务。
我完成了任务,但代码质量大多从糟糕到一般,随着时间推移逐渐改善。
当我最终理解领域知识并能做出更大范围的决策时,我开始提前撰写设计文档,代码质量也得到了显著提升。
现在,当我分配工作给更初级的工程师时,我会给他们一份高层次的设计文档,其中一些细节缺失,但他们交付的工作质量比我当时更高,而且他们似乎也提升技能的速度更快。
然而,这取决于我在这个阶段做出正确的决策,而这并不总是能做到,所以并非万无一失,但整体软件质量的提升是显而易见的。
那些为初级工程师提供完整(或合理)规格说明的人是幸运的,他们试图根据一本书的内容拼凑出整个系统。
我的经验是,撰写设计文档本身并不那么有争议,真正有争议的是审核过程。
有没有人对如何让审核过程更具建设性且更快速有任何见解?
我对这件事的看法:
首先明确你想要解决的问题并识别利益相关者。然后与每位利益相关者进行一对一会议并获得批准。
提出API方案。再次进行一对一会议以获得批准。
制作高层次架构图。再次寻求批准。
开始正式撰写设计文档并启动正式审核流程。
若规划得当,步骤1-3可在一周内完成,这将使设计文档争议性大幅降低并加速审核流程。
一些我认为有用的建议。
– 指定一名工程师作为最终决策者。虽然要收集他人意见,但必须有一人确保设计具有一致的愿景并符合目标。若非关键决策耗时过长,直接做出选择并推进即可。
– 明确项目目标。亚马逊采用PRFAQ流程,首先需撰写以客户为中心的新闻稿,详细说明客户为何应对此项目感到兴奋。这有助于将设计讨论聚焦于客户需求。
– 明确非目标或不会做的事情。
– 在评审会议开始时,让所有人阅读文档。该文档应描述所有相关背景。阅读完文档后,所有人都应具备足够的背景知识来理解和讨论设计——所有人都应对设计有相同的理解(即不会对我们讨论的文档版本产生混淆,也不会有人因事先没有足够时间阅读文档而只是粗略浏览)。
– 要求参与者在阅读过程中添加评论,作者可实时回应这些评论。待所有人完成阅读后,这些评论将作为需要讨论事项的清单。
– 确保文档是绝对的权威来源。如果某项内容未在文档中提及,则表示我们不计划实施该内容。这可避免以下情况:与某人讨论某个想法后,进一步调研后决定不实施或以不同方式实施,但审核者误以为该内容仍将实施,只是文档尚未更新。
我认为审核流程中存在人为因素。我见过许多设计方案被否决,仅仅因为“这应该由B团队而非你们来设计和实现”。问题是这种情况可能出现得太晚。有时这会对投入大量精力到设计中的工程师的职业发展造成打击。
但这难道不比被取消的代码(尤其是正在运行的代码)更好吗?我认为被取消的设计表明你没有理解自己对公司(或管理层对你的期望)的价值贡献,这才是职业发展中应关注的核心问题。
是的,设计比实际实现更便宜。并不是工程师不理解价值,而是大多数时候是管理层/项目经理无法在较长时间内最终确定方案。有时我感觉这只是某些情况下的政治因素。难道你不需要为一些高可见度的工作而奋斗吗?
这是一个好问题。有趣的是,我是初创公司的技术联合创始人,所以从未考虑过区分高可见度和低可见度工作。我想我们规模还不够大,所以我更倾向于从高影响/高成本和低影响/低成本的角度来考虑。我的非技术联合创始人会在产品指标有所提升时表扬工程师的工作,即使是些琐碎的任务也会如此。我更关注工艺水平,但我也认为应该关注影响。
我也曾在大型公司工作过,所以你提到的关于争取工作的观点很有道理。我也认为这是正确的。
1. 如果你在争取高可见度工作时获胜,这表明你可能是适合这个职位的人。公司不会让你做对你有利而对公司不利的事情。
2. 你也可以选择不争取,转而寻找其他具有高可见性潜力的问题来解决。也许这属于项目经理或工程管理层的职责范围,工程师可能对分配的任务感到无能为力,但这更多是文化问题。我认为,当工作量/预算/赞誉不足以满足人员需求时,政治斗争会加剧,这更多是情境问题而非文化问题,在我看来。
同意。关于第二点,这确实是团队/组织的文化问题。值得注意的是,在公司层级的高层,确实存在工作量(符合预期范围)少于人员(希望从事更高层次工作的人员)的情况。
这往往反映出对蓝图与实际构建之间关系的误解。简单事物的蓝图就是其构建方式。即使是复杂事物,对于新事物而言,这一原则大致成立。
然而,对于旧事物和复杂事物,蓝图更多是描述了可能的构建方式。且当构建者是他人时,若想对该陈述有信心,必须对构建过程与蓝图进行审计。
我在敏捷/Scrum团队工作。你在这种环境下有过跟踪设计文档工作的经验吗?由于对解决方案的调查和与利益相关者的沟通可能扩大范围,很难估算设计文档需要多长时间。
如果你的估算很重要,那你做敏捷的方式就错了。预留一些时间,做一些工作,重复。
但你必须估算才能知道一个冲刺能完成多少工作,对吧?如果估算错误其实没什么影响,但它有助于将一定量的工作安排到特定时间段内
在工作中,我们称它们为蓝图 :)。这是一种在编写任何代码之前获取早期反馈的绝佳方式,对于可能忘记考虑故障情况和可操作性的初级团队尤为重要。
从更现实的角度来看,代码本身就是蓝图。编译器/解释器为我们奠定了基础。
在快速迭代的情况下,如何平衡全新产品的编码与文档工作?
工程师实际做什么取决于他们所处的激励机制。如果交付始终被置于一切之上的优先级,那么文档工作必然会受到影响。
如果有人在文档工作做得不好时仍能晋升,现在你知道为什么会这样了。
我在谷歌工作了4年。关于谷歌的文档工作,有一件事一直让我感到惊讶:他们使用谷歌文档(和其他人一样),但似乎从未对改进这个糟糕的工具表现出兴趣。它始终以打印为导向,这在当今几乎毫无意义(你上次打印谷歌文档是什么时候?),缺乏处理预格式化文本(如代码)的功能,几乎不支持数学公式等。事实上,与早期版本相比,它实际上变得更不适合技术文档编写,因为早期版本至少允许你定义自己的段落样式。我曾希望Google Colab能发展成一个更适合撰写技术规范的通用工具,但它似乎并未朝这个方向发展。
我觉得谷歌已经放弃了。iOS版Gmail应用糟糕且 bug 不断。网页应用现在甚至有了加载界面。自被谷歌收购以来,GSuite 产品套件几乎没有进步。谷歌云正被亚马逊和微软碾压。我想他们还有搜索业务,但它正被广告填满且日渐疲软。虽然我不会很快做空GOOG,但各位,这可不行啊!
人们不明白谷歌如何激励员工。你因“抢功”而获得晋升,尤其是“推出新项目”时。我特意提到“抢功”,因为如果你无法为自己的工作“抢功”,那还不如什么都不做;一个典型例子就是接手别人启动但放弃的项目并推出。需要注意的是,你不需要做太多工作就能“抢功”——只需在会议上与比你资深的人一起“领导”一个已经即将推出的项目即可。
改进现有事物不会让你得到任何东西。结果就是,我们有了四款不同的即时通讯应用,没有一款是好的,还有一堆停滞不前、看似被放弃的产品。原因很简单:那些足够聪明、理解游戏规则的人会在项目启动后立即转向下一个大项目。
尽管如此,我仍然更喜欢GSuite而不是Office。微软确实把标准定得很低。
> 尽管如此,我仍然更喜欢GSuite而不是Office。微软确实把标准定得很低。
这取决于具体功能。你可以从我冰冷的手中夺走Excel;OneNote仍然是一款令人惊叹的软件,并且正在获得一些不错的更新; Outlook本身对于80%的使用场景来说相当可靠,拥有快速的iOS/Android应用;通过一些VBA脚本,一切都可以根据你的喜好进行调整。
OneDrive在注册时提供的免费空间比Google Drive更多,我认为,尽管创建Google Docs/Sheets/Slides不会占用GDrive的存储空间——这是我们做出决定的关键因素。
iOS 和 Android 上的 Outlook 实际上并非 Outlook 本身,而是 Accompli。如今的桌面版 Outlook 仍有不少改进空间。
而且,我的妻子是会计师,因此 Excel 对她来说是必不可少的。她确实可以在 Sheets 中完成大部分工作,但 Sheets 缺乏与多年来积累的各种后台系统的集成。
这是个普遍看法,但并不完全准确。你需要能够衡量所做的改进,这可能使一大类潜在改进在性能上不可行。但如果你能展示满意度评分、延迟数据、操作完成指标,甚至只是客户评论说问题已解决,这已足够成为尝试变革的理由。该系统鼓励你不要专注于那些“感觉良好”的事情,而是专注于可量化的事情。正如你所想象的,这有其利弊。
综上所述,我认为更大的问题在于愿意推出不符合高标准的产品。例如,新版网页版Gmail的发布速度比旧版更慢。这是为了更快地将新功能推送给用户,但从产品卓越性的角度来看,这种做法并不理想。没有像史蒂夫·乔布斯那样的人物告诉我们Pixel 4的外观不够出色,因此我们应该重新设计。更像是有一系列市场调研结果,而手机的设计只是为了满足这些需求。
m0zg提到的观点仍然成立。系统鼓励对指标进行欺骗性报告。如果你能通过改善指标来获得功劳,即使在过程中造成了更大的损害或没有真正做出贡献,你仍然会得到晋升。
为了晋升目的,发布一个半成品但“新”的垃圾产品,其效果简直是10倍于通过 incremental improvements 获得的职业发展速度。你得费尽心思才能通过 incremental improvements 获得同样的职业发展速度。
这似乎与我一位曾在那里工作过的朋友的经历一致,以及他如何被奖励(或未被奖励)。
我忍不住觉得他们奖励的是正确的事情——新颖的东西可能最能吸引落后者加入谷歌平台。
不幸的是,这让人觉得谷歌只是在浅尝辄止。
> 注意,你不需要做太多工作就能“抢功”——只需在会议上与比你资深的人一起“领导”一个已经即将推出的项目即可。
这是我见过的标准晋升方式。这些人怎么不觉得恶心?
这是真的。我在谷歌工作了五年。有些谷歌员工会抢走你的功劳。尽可能快地远离这样的人。
评论发现功能也糟糕透顶。很多时候,关于文档的讨论中包含的信息并不一定属于文档本身,但对未来读者仍有价值。解决评论会让查找这些信息变得困难得多。
关于以打印为导向的界面,你说得完全正确。Writely和早期版本的谷歌文档不会强迫你假装自己在纸上写作。我希望有一个“适用于文本文件的谷歌文档”!
另一方面,我喜欢Google Docs的简洁性,我们在我的(非常大型)雇主处使用它处理一切事务,它特别适合技术人员与业务人员之间的协作。熟悉的文档界面适合业务人员,而添加和分配任务作为评论的功能使整个体验无缝衔接。
是的,它处于一个非常奇怪的细分市场,介于更简单的文本/笔记导向的Markdown和更注重打印的Word/Pages之间。如果需要打印时看起来不错,Word显然更优,但对于不需要打印的简单任务,Markdown几乎总是更好,除非你需要收集反馈或进行实时协作。这很好,十年前协作确实是杀手级功能,但现在还有谁真的需要打印?似乎大多数学校不再接受纸质作业,几乎每个人都有手机/打印机和互联网,那么为什么还要如此强调打印?我希望它能演变为以数字优先的体验,同时提供类似阅读模式的简化功能,或者打印提示,如页面断开等,如果有人真的想打印。
你试过Dropbox Paper吗?尽管名字听起来像是打印工具,但这是我用过最不以打印为中心的编辑体验。据我所知,在我现在的公司,它比Google Docs更受欢迎,尤其是在设计文档方面。
在我的工作场所,我们开始使用Confluence进行一些项目,效果非常高效。我仍然讨厌JIRA,但Confluence在技术协作和文档方面表现出色。
我的经历也是如此——我们完全依赖Atlassian。
Confluence 非常出色,Bitbucket 还行但一般,而 JIRA 则是一团糟,无论是设计还是功能都令人失望,但管理层和类似管理层的人却很喜欢它。
在我公司,我们使用内部维基或 Quip 进行此类工作。前者支持版本控制且采用有效的 Markdown 格式,后者则内置实时图表或电子表格功能。
亚马逊同时使用了维基和Quip,但两者都糟糕,只是糟糕的方式不同。
维基编辑起来异常缓慢(渲染也慢,页面渲染通常需要约2秒,还不包括一些异步渲染的图表)。
Quip适合快速编辑,但涉及代码格式化时表现糟糕。它甚至比Google Docs更偏向于打印格式。页面宽度固定,格式非常 rigid,表格设计糟糕。
> 谷歌文档中有一点一直让我感到惊讶,那就是他们使用Google Docs
您何时在谷歌工作过?现在有支持Markdown的维基工具用于内部文档。它支持预格式化代码、图表等。
我认为目标受众主要是非程序员,也就是普通人。这是一个通用工具,因此功能集相应丰富。
没错。再添加一项:不支持Markdown。
我倾向于尽可能减少文档,或保持其尽可能模糊。
这是因为我来自一个坚持要求极其详细、正式、经所有人(包括男厕所管理员)批准的文档的环境。
这些文档变成了“混凝土雨靴”[0],将本应是敏捷、迭代的项目变成了耗资巨大、耗时漫长、最终交付结果无人想要的瀑布式巨无霸。
我怀疑我当前的流程[1]对许多组织来说是不可接受的,因为它基本上要求所有参与者都极具经验,并且作为团队合作多年。
我逐渐意识到,“部落知识”并非如人们所言的可怕存在,而是实现高质量、快速、适应性开发的一种方式。主要问题在于,它需要良好的、富有同理心的管理,长期保留经验丰富且能力出众的人员,以及“学徒制”模式。这些概念在当今企业界并不流行(至少在美国是这样)。
[0] https://medium.com/chrismarshallny/concrete-galoshes-a5798a5…
[1] https://medium.com/chrismarshallny/forensic-design-documenta…
我认为人们需要意识到的是,像谷歌这样的公司与银行等机构的工程文化存在极大差异。
设计文档在谷歌能发挥作用,是因为其工程团队高度分散且独立,成员大多是理性的人,且几乎不受团队外部指令的约束。但在那些存在表现不佳、微观管理或越权的团队的公司中,设计文档往往会失败(例如,那些无所事事的工会化项目经理,业务开发部门告诉开发人员要实现哪些功能(甚至具体到细节),质量保证团队被激励去无限寻找“缺陷”以显得忙碌等)。
但我认为这是目标根本不一致的症状。设计文档被那些以构建/改变事物为目标的组织使用。许多组织对变革持抵触态度,其流程也反映了这一点,例如通过过于繁琐的文档、复杂的审批流程等。
是的,你说得对。
但我对许多组织的动机已变得相当愤世嫉俗。
如今,似乎 everyone 都在推动一种环境,其中相对缺乏经验(不一定是低薪,但缺乏经验)的开发者不断流动,在公司短暂停留后便离开。
这需要一个规范化、根深蒂固的结构,需要被记录和支持。这适用于现代的“敏捷”公司,也适用于更传统的“保守”企业。新加入的人需要快速融入,被榨取每一分生产力,然后在不再有用时被淘汰。
这种模式既得到员工的支持,也得到管理层的支持。薪资水平可能相当高,尤其是对于那些适应能力强、能迅速上手的人。
但绝对没有比一个经验丰富、团结协作的团队更重要的了,这样的团队已经形成了共同的语言和目标。
我很幸运能成为这样一个团队的一员。团队中资历最浅的人也有十年经验。每个人在软件开发领域都有超过30年的经验,我们完成了一些相当复杂的任务。遗憾的是,我们仍然受到我之前提到的那种结构的限制,很多我们的产品最终被封装在质量较差的框架中(我们做的是“引擎”代码)。
>我认为人们需要意识到的是,像谷歌这样的公司与银行等机构的工程文化存在极大差异。
我必须指出,这种情况并非普遍存在。我曾为几家金融机构工作过,通常会在启动任何大型项目前遵循某种设计流程(如上所述,我认为RUP流程是一个非常有用的框架)。大多数情况下,设计流程通常会受到欢迎,因为人们乐于有人愿意从利益相关者到数据库架构和类图,对问题进行全面的视角分析。该流程有助于项目管理,明确利益相关者,并描述在项目转入生产环境后所需的支持要求。
银行实际上非常喜欢有人详细说明所有这些内容。
在我所了解的几个案例中,即使我已经离开项目多年,我的设计文档仍然被引用,因为它们捕捉到了大家容易忘记的最重要内容——基本上就是做出某些决策的“原因”,以及被否决的替代方案。
一个好的架构图也不会过时 🙂
> 基本上要求所有参与者都必须极具经验,并且作为团队合作多年
没错,这就是问题所在。企业无法将这种方法固化为流程,因为他们无法对此做出任何保证。
你的方法是“魔法师会议”。这是一种高产出方法,适用于某些问题领域,但(a)它不可重复,(b)它不可持续(如果关键数量的魔法师离开会议,公司该怎么办?放弃并关闭?)
> 放弃并关闭?
在某些情况下,是的。这就是必须发生的事情。
如果商业模式依赖于“魔法师会议”,那么他们就是关键路径资源,就像主要供应商或商业伙伴一样,如果他们退出,公司也可能面临同样的灭顶之灾。
如果企业拒绝将该资源视为宝贵且关键的资源,那么他们就不配继续经营。
管理此类团队并非学校能教授的内容。这需要经验,同时也需要一种同理心,坦白说,这种同理心在当今商业文化中几乎不存在。
确实。因此,为了企业的短期和长期生存(因为我们无法事先知道魔法师会议是否稳定),企业应该做的正确事情是尽量减少形成这种情况的可能性。
企业是以降低风险为目的的结构。一群核心专家,如果没有他们,企业的表现就会下降,这是一种风险。而且是一种难以量化的风险。
除非,当然,企业并非旨在最小化风险,而是为了保护某个风险较低的结构免受过度风险暴露。例如,一家由天使投资者资助的初创公司,尝试实验性技术,希望找到一个能被大型企业收购的 jackpot 新系统。如果失败,只有天使投资者的资金会损失。如果成功,一家风险厌恶型企业可以收购一个有价值的资产。
但这家企业为了维持长期风险 profile,首先想做的就是解雇这些“魔法师”。;)
但……这些“魔法师”能做一些独特的事情。大多数时候,拥有他们的唯一原因,就是做一些“通用”团队无法完成的事情。
> 主要问题在于,这需要良好的、富有同理心的管理,长期保留经验丰富、能力出众的人员,以及“学徒制”模式。
在我看来,这听起来像是一个理想化的环境。我怀疑这种环境在任何流程(或缺乏流程)下都不会失败。
文档不必“极其详细、正式、经所有人(包括男厕所管理员)批准”。那可能是最糟糕的类型。我认为OP/谷歌的设计文档似乎确实倾向于那种风格,可惜了。我好奇这在实际操作中是否如此?尤其是考虑到长度——10到20页对我来说似乎过于详细。不过我猜在大型项目中,所有组件的实现细节累加起来确实会变得相当庞大。
我对OP的“审核”部分特别有意见,他们提到要向大量受众开放审核。我怀疑这在实际操作中是否真的会发生。根据我的经验,将某事开放给多人审查往往会演变成“厨子太多”的局面。基本上就是你所担心的“连男厕所管理员都参与审批”的情况。这种情况最终会演变成无谓的争论。实际上,我猜它会被开放给所有人,但真正被期望提供反馈的可能只有一两个人。
我仍然认为,我宁愿选择过于正式化的流程,也不愿依赖部落知识。你看不见部落知识背后的真相是,那些掌握大量知识的人不断被中断来回答这些问题。这在规模上变得非常低效。更不用说回答问题的人所承担的额外负担——比如寻找关于问题的旧线索,如代码或邮件。再加上开发人员工作中最大的敌人:上下文切换。我曾经是拥有部落知识的人,这基本上成了我的全职工作。这对工作保障很有帮助,但我遗憾的是,因为没有更积极地撰写文档,我浪费了大量时间。
_> 部落知识背后不为人知的一面是,那些掌握大量知识的人经常被不断打断,不得不回答这些问题。这在规模化后会变得非常低效。更不用说回答问题的人所承担的额外工作量——比如寻找关于问题的旧线索,如代码或邮件。
完全正确,这就是“良好管理”发挥作用的地方。
我管理过之前提到的团队,我认为自己做得不错。
我最重要的任务就是保护团队免受公司内部的各种干扰,尽可能承担结构性开销,并充当“守门人”。
我管理这个团队长达25年。在这段时间里,我们完成了许多工作,但也经历了许多“教训”。我当然也犯过错误;其中大部分是由于我忽视了“管理屏障”的责任,试图以错误的方式成为团队的一员。
我通过业余时间的开源工作保持了技术能力。没有人愿意为我的技术技能付费。
这种环境让我想起了康威定律[1]——代码结构反映组织结构。
听起来问题在于决策权分散在太多人手中。详细文档只是副作用。移除文档可能无法解决问题。
[1] https://en.wikipedia.org/wiki/Conway%27s_law
元数据:为什么你链接到Medium,而文章也发布在你的网站上,我假设如果存在差异,你的网站是权威版本?
此外,我审查了你的隐私政策,虽然我不是律师,但我认为你的cookie弹出窗口并非多余。根据我对GDPR的理解,如果设置的cookie严格用于满足明确请求,则无需单独征得同意。例如,如果用户勾选了“保持登录”选项,您无需单独请求设置“wordpress_logged_in_xxxxx”cookie;用户已通过勾选该选项给予了同意。同样,当用户登录时设置会话cookie,或用于保存设置的cookie也无需单独请求同意。更不用说,如果没有明显的登录链接,我猜您可能是唯一这样做的,这种情况下您本就不会在他人电脑上设置cookie 🙂
这些内容仍需在隐私政策中描述,但无需向用户展示;仅当使用cookie进行用户未明确请求的操作(如跟踪)时,才需显示同意框(无论使用独立跟踪cookie还是利用登录cookie实现)。我未在您的网站隐私政策中看到这些内容。
无需向读者弹出同意提示框是GDPR为像您这样的尊重隐私的网站带来的巨大优势!
谢谢!关于弹出框的建议很好。我会移除它。
我很乐意链接到我的常规网站,但我想人们更喜欢Medium;可能是因为其标准化的布局(我并不喜欢),以及使用应用程序和语义API钩子的能力。
我的网站上有几个系列在Medium上不可用 [0][1][2][3][4][5]
[0] https://littlegreenviper.com/series/swiftwater/(我将其中一篇重新发布到了Medium)。
[1] https://littlegreenviper.com/series/spm/
[2] https://littlegreenviper.com/series/bluetooth/ (该文章曾在HN上短暂排名第一 – 圣帕特里克节)
[3] https://littlegreenviper.com/series/bluetooth-2/
[4] https://littlegreenviper.com/series/streaming/
[5] https://littlegreenviper.com/series/stylist/(这篇文章已有十年历史)
如果你是谷歌员工,一个有趣的活动就是去阅读古老的设计文档,比如Bigtable的原始提案。这些文档大多很简短,而且是由传奇人物撰写的。它们是你公司的《联邦党人文集》,为公司如何发展到今天提供了真实的背景。特别是,我总是喜欢阅读那些描述了最终未被实现或后来被移除的内容的令人震惊的部分。思考他们为何当时认为这些内容重要到值得记录下来,是一件有趣的事。
现在我写了以上内容,不禁感到有些遗憾,因为开源软件的设计文档并不多,即使是那些源自拥有良好设计文档文化公司的项目也是如此。有没有讨论过Kubernetes或gRPC中被考虑但最终被否决的替代方案的文档呢?
我曾为K8s编写过一份设计文档/产品需求文档(PRD),其中详细阐述了基本API、分布式架构,以及它与开源项目和市场之间的关联原因和方式。离开谷歌时我弄丢了这份文档。据我所记得,那是一份谷歌文档,且未提交到源代码控制系统。
有人一定分享过访问权限才能帮你找到它吧?
那些“传奇人物”很早就加入了公司,拥有如今已不存在的机会。为何要崇拜他们?其中一些人并非善类。如果公司允许,有许多人也能做出传奇之事。
杰夫比的建议很棒!等等,等一下。
相关链接:https://www.joelonsoftware.com/2000/10/02/painless-functiona…
我的看法:
如果你不在单独的文档中以文字和图片的形式明确说明事情,那么你最终还是会以临时的方式来处理。
你的“非规范”内容现在会分散到多个工具和渠道中,这些工具和渠道很可能无法相互沟通:邮件、即时消息、文件存储、笔记、电话通话及讨论(即存在于你的脑海中/记忆中)、Trello/Asana/Jira等,以及人们的想象和预期中。
规范就是你本就会做的事情,只是将其以书面形式记录在一个统一维护的位置。你可以对其进行版本控制并迭代修改。所有相关方可以在迭代和讨论的前后阶段拉取并查看它。
规格文档无需一成不变。它可以随着你构建的事物而迭代地增长、缩减或改变。它还可以明确规定一些你特意不应做或无需担心的事项。
“设计文档”似乎就是这样一种东西,只是换了个名字?
此外,规格说明书有助于更清晰地沟通,因为你最终会为流程、UI 元素、技术组件等定义一个“术语集”。
我认为有用的工具:
– Markdown + CSS + 某种工具将其转换为 HTML/PDF
– Graphviz,尤其适用于状态机和决策树,我更倾向于输出为 SVG 而不是 PNG。
– UML图或类似工具(如适用)
设计文档并非严格意义上的规范。它是讨论的媒介,也是当时人们想法的快照。这类文档会很快过时,且不期望有人更新它们(务必在文档上标注日期!)。
我认为规格说明应提交到代码库中,可以通过某种代码注释,或在文本文件中与代码并列,具体取决于你正在做的事情。
感谢你的澄清。我的问题是:既然我已经有一个维护良好的规格说明,何时需要设计文档?它们是作为草稿使用,还是完全独立的文件?
我倾向于在以下情况下使用设计文档:(1)问题模糊不清,(2)没有明显解决方案但有多个候选方案,(3)需要多方反馈。
其主要功能(如其他人提到的)是:(1)促进共识,(2)记录特定时间点上的思考过程。
我认为设计文档适用于当你对解决方案的细节了解不足时。
我发现RUP的愿景文档是一个非常好的系统规格框架。它能将用户置于核心位置,确保所构建的系统是人们真正需要且具有现实商业价值的。
我发现设计文档非常有用,即使没有人阅读它们,因为它们迫使我在开始(更昂贵的)实施过程之前澄清我的想法。
然而,我也注意到设计文档中存在两个非常常见的问题:
– 许多设计文档没有明确说明设计旨在解决的问题。通常对设计最好的回应是“这个问题不值得解决”,或“已有其他系统解决了这个问题”,或“你应该考虑完全不同的方法”,但若没有明确说明问题及其解决的重要性,就难以判断这些情况。
– 人们往往过于关注设计细节,而非需要做出(或已做出)的重要决策、这些决策的替代方案及理由,以及决策所基于的假设。一年后,你可能不会太在意某个API参数的具体细节,但你很可能会在意为何选择该API而非其他选项,因此记录下这一决策过程是有用的。
将设计文档视为系统背后思维过程的提炼,而非构建某物的高度概括性描述,这种视角是有益的。
我喜欢设计文档的概念,但在30年的软件开发经验中,我从未见过一份真正做好的设计文档。TFA在概述理想设计文档应包含的内容方面做得还算不错,但并未提供任何关于如何创建一份真正符合这些标准的设计文档的建议。
谷歌的一个小技巧是提供“标准”模板作为设计文档的起点。这些模板包含帖子中提到的所有章节,且每个章节初始时都填充了该部分所需内容的描述(有时还附带其他支持材料的链接)。
并非所有人都能勤勉地填写所有适用章节,但这确实有助于为流程带来一定统一性。
我认为迫使团队提出这些问题比让文档完美更重要。我参与过太多类似“React前端、Node后端、Mondo数据存储是解决这个和所有问题的完美方案”的讨论,而没有考虑其他选项。
在引入新成员时,拥有此类文档也具有价值。我目前参与的项目在我加入前已启动两年,我非常希望有一份文档能解释为何选择Active Directory而非其他认证机制。
Basecamp的提案和框架有点像设计文档,但这里似乎缺少了一些内容?你可以看看,它们以令人耳目一新的方式呈现了易于理解的概念。
OP链接到一个实现其理念的设计文档模板:
https://www.industrialempathy.com/posts/design-doc-a-design-…
代码也是如此,对吧?这是一个好主意,但30年来我们从未见过代码被很好地实现。
“很好”是一个模糊的词。
但代码实际上是有效的(通常最终会有效)。如果你没有代码,你就没有软件。如果你没有设计文档……通常和有设计文档没什么区别。
根据我的经验,情况并不一样。设计文档允许就最终代码展开讨论,而代码审查在这方面做得较差或效率较低。这些讨论为我们节省了时间,并让我们确信解决方案是解决问题的最佳方案。
我在谷歌工作了一段时间,几年前我想发布一个开源项目。由于代码将托管在Git上,将设计文档也放在那里是有意义的,所以我就在项目根目录下添加了一个DESIGN.md文件。这产生了一个令人惊喜的效果:有时,当人们对项目进行重大修改时,他们会更新设计以反映这些变化!
请参阅这个精彩的提交作为示例:https://github.com/google/stenographer/commit/d678531a3e5a87…
这是一篇很棒的文章。我最近花了很多时间撰写设计文档。我们从中获得了巨大的价值。
我参与的项目通常是与多位开发者合作的。确保团队对我们正在构建的事物有相同的愿景至关重要。一份好的设计文档是团队同步对所构建事物认知模型的工具。
我们还经常与其他团队(如安全、基础设施、运维、其他业务部门等)合作,这些团队都对我们的工作有利益相关。一份好的设计文档有助于与他们达成共识。审核过程为他们提供了表达关切的渠道。在编写任何代码之前解决基础问题要容易得多。
文章中未明确提及但对我来说非常有价值的一点是包含参考资料。根据我的经验,良好的设计文档通常包含一些参考文献。例如,链接到我们计划使用的软件的文档、链接到解释我们计划采用的架构部分的 AWS 博客文章、链接到解释我们计划实现的算法的学术论文等。良好的参考文献支持设计文档,并帮助读者填补他们可能存在的知识空白。
>在编写任何代码之前解决基础问题要容易得多。
这让我想起了1-10-100规则。在设计阶段修复一个问题需要1个单位的努力,在开发阶段修复一个问题需要10个单位的努力,在上线后修复一个问题需要100个单位的努力。
我们是否有谷歌、脸书、推特等公司创建的设计文档模板?
并非要唱反调——我的问题是,目前缺乏设计文档的规范模板(有人将其与蓝图进行过比较)。如果我们能获得行业领军企业认可的模板,那将非常方便。否则,每个人都会按自己的方式创建文档,以适应各自的使用场景。但这种做法会缺乏一致性,且缺少必要的内容。最终,这些文档会随着时间推移逐渐失效。
此外,当设计发生变更时,这些文档需要更新。但人们通常不会这样做。一段时间后,设计文档就会变得过时且成为负担。
谷歌的标准设计文档模板被称为Bluedoc。
一个示例在此:https://docs.google.com/document/d/18hYAQCTsDgaFUo-VJGhT0Uqy…
删除所有内容,只保留标题,你就得到了一个Bluedoc。
还有一些领域特定的标题在使用中:隐私、伦理和安全是非常常见的。
是的,监控和日志记录也是常见的。
> 如果我们有一个经行业领军企业批准的模板,那将非常方便。否则,每个人都会根据自己的使用场景自行创建模板。
我在软件工程中看到的一个常见错误是,采用与自身团队或公司不匹配的工具和流程。当然,可以参考行业内其他人的做法,但最终你需要找出最适合自己的方案。对于像谷歌这样的公司,规范的需求可能与一个由10人组成且保持持续沟通的团队的需求大不相同。
我认为如果有一个 rigid 规范,它将与本文档早期提出的一个观点相矛盾(我认为这一点值得注意):
> 规则#1是:以最适合特定项目的形式编写它们。
这是一条令人不满意的规则,但我认为它很重要,因为每个团队/问题领域等都不同,过于严格的规则往往会导致文档变得肤浅。
然而,这显然无法解决你提到的另一个问题:
> 此外,当设计发生变化时,这些文档需要更新。
… 但如果大家对文档的目标有共同理解,这可能没问题。如果目标是就实现方案达成共识(而非作为活文档),那么在共识达成时,文档可能已完成其使命,即使后续设计发生变化。如果目标是记录系统的活文档,那么本文中提到的粗略格式可能不合适。
我曾听过一个关于设计文档的术语,即它们最终成为“决策日志”中的一环,这让我在文档过时时感到好受一些。这些文档最终成为特定项目/系统在某个时间点上集体理解/意见的记录,即使与实际情况脱节,这种记录本身也有其优势。
这里的前几点绝对正确。这些文档是与组织内一群人沟通、获取反馈(并迭代)一个想法的方式。不同组织会有不同的沟通方式和需求。
是的,我认为文档在项目生命周期内保持同步才是关键。之后,它可以作为历史记录。
有人知道哪里可以找到真实的设计文档示例吗?最好是遵循这篇指南的。我指的不是玩具示例,而是实际被真实的人或组织使用的文档。我的工作场所也有设计文档,但它们充满了杜撰的术语,所以我对这种事情已经感到厌倦。
Beancount(一款基于文本的会计软件)的作者是谷歌员工,他最近分享了https://docs.google.com/document/d/1qPdNXaz5zuDQ8M9uoZFyyFis…的链接,这是一份相当标准的谷歌风格设计文档。
以Deno设计文档为例https://docs.google.com/document/u/0/d/1_WvwHl7BXUPmoiSeD8G8…
谢谢!这篇文章很有趣,让我对更好的工作环境充满希望。所以这基本上是一个经过深思熟虑的 GitHub 问题/对应的 PR,你同意吗?
Python的PEP(Python增强提案)是设计文档的良好示例,它们描述了问题、提出的解决方案以及理由:https://www.python.org/dev/peps/
这是我关注的一个与为Flutter添加多窗口支持相关的提案:https://flutter.dev/go/desktop-multi-window-support
我也发现了一些Chromium的设计文档非常有趣:https://www.chromium.org/developers/design-documents
我长期使用一款由谷歌开发的开源虚拟化工具包。该工具包包含大量此类设计文档:
http://docs.ganeti.org/ganeti/master/html/#implemented-desig…
作为最终用户,我一直很享受阅读这些文档。
据我所记得,我曾在Veritas泄露的文档中看到过它
作者在此。如有任何问题或反馈,请随时告知。
我认为这非常有帮助。我已将它发送给我的经理和团队中的其他人。我们公司最近经历了一次转型,新产品负责人喜欢将实现手册作为设计文档发送给我们,因为这是他们多年前的做法。我们一直在努力让这些文档适应我们的流程,希望这篇文章能帮助改变思维方式,或至少帮助我们达成共识。感谢撰写此文!
你好,马尔特!
这篇文章很棒。我同意设计文档是定义谷歌工程文化的重要组成部分。我建议任何愿意听的人,他们的公司也应该这样做。
这个帖子中很多人被瀑布式的需求文档或正式规格说明所困扰,我想指出为什么我认为设计文档(至少在谷歌)与这些不同且更有效。
我倾向于将设计文档视为团队的沟通机制,而非项目产出的成果。当你有想法时,你会写下:
* 你试图实现什么?
* 为什么要这样做?
* 如何实现?
* 你考虑了哪些因素?
然后你将它分享给一到两位审核者,他们会提出很多问题,接着你再将它带到团队中,团队会提出(相对较少)的问题。分享环节是整个系统中的关键。正如你所指出的:
“此类审核的主要价值在于,它们为将组织整体经验融入设计提供了机会。最重要的是,确保设计考虑了可观察性、安全性和隐私性等跨领域问题,这是可以在评审阶段确保的。评审的主要价值不在于发现问题本身,而在于这些问题在开发生命周期早期就被发现,此时进行修改的成本相对较低。”
如果我打印出你的文章给别人看,我会用黄色标出这一部分。
与之形成对比的是,正式的文档系统很少记录“为什么”和“为什么不”。未来的维护者将拥有一份记录当时思考过程的文档,而非试图记录系统完整的实现计划。
希望这能为那些曾被传统方法烧伤的人提供一些背景。
编辑:拼写错误
我的问题是,如何在这一过程中避免无谓的争论?
“考虑的替代方案”部分是处理此问题的良好场所。在那里,你可以列出任何特定事项的所有正反论据,以免陷入无休止的争论。
通常,撰写文档的人拥有最多的上下文和专业知识,可以提供简短解释,说明为何某一选项可能是更好的权衡,即使存在明确且合乎逻辑的反对论据。
拥有数据也很有帮助。依我之见,很多无谓的争论都是缺乏依据的猜测,可以通过概念验证、基准测试、冷静的比较表格、与行业内其他人的讨论记录等来消除。在我公司,涉及重大技术决策时,通常会与FAANG或其他公司中具有相关经验的人员会面以收集信息。
这很好。在我公司,我们通常会创建设计文档,我见过这里描述的每个反模式,以及它们更具信息量/实用性的对应版本,但从未见过一个地方能如此简洁地列出“该做/不该做”的清单。
一条反馈意见——我喜欢在系统图旁附上序列图来详细说明交互。我认为这与以非正式方式记录API的目的相似,且能提供较高的信息密度(我并不期望每个人都能阅读并消化整份5-15页的文档,图片能帮助人们记住重要内容,并在未来有可参考的依据,我认为)。
如何让那些对特定领域有知识的团队投入工作,即使这不是他们的目标或他们正在关注其他事情?
在这里,真正有帮助的是建立一种共同所有权的文化。如果一个团队拥有知识,最好的办法就是与他们合作,让他们与你分享这些知识。但如果他们太忙,或者不愿意分享,那么你将不得不继续前进,而无需他们的参与。你不能让这样的团队成为进步的瓶颈。
同样,如果你所在的团队拥有重要的知识,那么广泛分享这些知识非常重要。准备大量优质资源以帮助传播这些知识。不要试图充当守门人或小圈子,而是要成为知识的倡导者和推动者。如果你希望其他团队尊重你团队的知识,那么你需要确保他们认识到你拥有这些知识,并且你愿意分享它们。最后,最好采用赋权策略,而非所有权策略。鼓励并支持知识的消费者自行解决问题,而非要求你们对每个问题发表意见,或参与每一次设计评审。
当然,这一切都需要领导力,因为这是文化实践。领导层必须投资于团队的知识文档化和共享。领导层必须奖励和认可知识分享者,同时也要识别并引导知识囤积者改变其行为。领导层必须识别出团队何时成为阻碍进展的障碍,并采取措施增加资源,或如上所述,鼓励团队绕过障碍继续推进。“某某是网络专家,但他不肯帮助我们解决这个问题。” “好的,我会想办法争取他的时间,同时让我找外部顾问,或者我给你授权自行解决,因为他们正在阻碍进展。”
最后一种方法是你的最后手段,但你不能害怕使用它。我实际上觉得谷歌在这方面问题不少(前员工反复讨论的“首席工程师垄断问题”现象,以及我在开源项目中亲眼所见的情况)。
我知道这不是一个令人满意的答案,但像设计文档或任何$软件开发方法论这样的工具并不能帮助修复破裂的公司治理。
具体来说,我会尝试让解决我的问题成为其他团队的目标。例如,在规划季节邀请他们参加峰会并达成共同的OKR。
为创造价值的人付费。如果你认为设计文档有价值,就为撰写更多更好的设计文档的人支付更多报酬。
实际有效的设计文档将极具帮助
哈哈,谷歌的设计文档……
我在谷歌的六年里大概读过数百份设计文档。
我认为其中只有少数几份设计文档,不到10份,被认为清晰、简洁且有条理。而这些文档大多是事后总结,在系统已经实施并运行一段时间后才撰写。
新的设计文档,作为活跃项目中实际的工作文档,无疑主要是一种流程机制,用于征集设计输入并获得利益相关者的支持。
这是一种形式主义,旨在表明项目负责人愿意“浪费”时间,并说服所谓的“审核者”认可项目的合理性。审核者通常不会认真阅读设计文档。只有利益相关者,如团队负责人、潜在客户、合作伙伴等,才会花时间仔细研究。这在某种程度上是利益相关者对设计流程进行指责的辩论场所。这也是为什么设计文档最初以Google Doc形式撰写的原因。
一旦设计获得“批准”,通常意味着大多数主要利益相关者已满意,且所有人都已疲惫不堪,而项目又具备足够的重要性以推动实施,因此获准执行。
此后,设计文档大多失去作用。文档中阐述的设计通常存在两种情况:1) 过于简单,无需参考设计文档,几分钟的讨论即可说明;2) 过于复杂,设计与实际代码产生偏差,设计文档难以提供有效指导。介于两者之间的设计文档极为罕见。
总之,软件工程项目中产生的任何成果似乎都只是组织人类互动过程的工具,除了作为高层次的激励性文件外,最终的代码+文档之外,中间环节似乎在工作完成后大多价值不大。
说实话,有时我甚至会撰写设计文档,即使没有人会阅读它。如果需要,它可以短到只有几句话。
主要好处是它迫使你:
1. 以战略性而非战术性的方式思考即将构建的内容。超越仅仅“我需要现在让它运行起来”的层面。
显然,链接中提到的组织优势也非常重要,但如果你只完成了上述1和2,那已经值得你付出努力。
文章并未指出系统可能出现偏差的方式。
设计文档在能够用1-2页简明扼要地描述一个重要/大型/复杂系统的工作原理及其设计时的权衡取舍时,是非常有价值的。
谷歌内部的一些团队将设计文档与晋升流程混为一谈,因此工程师们开始为每一件小事创建冗长且耗时的文档,作为晋升的依据。
这是一篇很棒的文章,如何生成既实用又不会耗费太多时间的设计文档是我一直在努力的方向。我遇到的一个难题是找不到行业内其他人是如何做的例子。有没有人找到过提供真实世界设计文档示例的资源?显然每个项目都不同,但我很好奇其他人是否会像这篇文章一样,公开他们通常使用的模板/大纲。
我感觉博客文章似乎为许多开源项目填补了这一空白,但如果有人找到更结构化的示例会很有趣。
坦率地说,我认为亚马逊的设计文化更为严谨。一个新项目(例如在Reinvent大会上发布)的设计过程可能长达半年以上。
设计深度真的能用时间长短来衡量吗?
是的,有些是来自评审者、合作伙伴团队甚至政治因素的干扰。设计深度通常非常深入,因为亚马逊有很多SDE1,招聘门槛相对较低,而设计需要非常详细才能确保安全执行
> SDE1,招聘门槛相对较低
作为一个SDE1……天啊,兄弟。
抱歉,我的意思是与谷歌/脸书相比……但这并不意味着生产力更高
再次,这真是个大问题。我真的不认为像我这样的人会喜欢被称为……嗯,笨蛋。
“非结构化文本,如设计文档的形式,可能是项目生命周期早期解决问题的更好工具,因为它可能更简洁、更易于理解,并且以比代码更高的层次传达问题和解决方案。”
我完全同意。我在 Uber 看到所有项目都一致使用设计文档的概念。这里它们被称为 RFC,并且在项目初期就被引入。我曾详细撰写过使用这些文档的经历,以及我确信它们如何帮助扩展工程文化 [1])。我观察到最令人惊讶的是,将这些设计文档发送给整个工程团队的效果非常好,直到组织规模超过一千名工程师。
[1] https://blog.pragmaticengineer.com/scaling-engineering-teams…
如果能在博客文章中看到实际的设计文档,而不是一篇没有主要参考资料的摘要文章,那将非常棒。(对一些设计文档进行事后分析会非常精彩!)
将设计文档流程引入工程师团队最困难的一点是提供具体示例作为起点,并确保反馈机制以使流程真正运转。如果团队一直只进行每周的Scrum会议,突然引入设计文档理念会非常突兀。此外,设计文档通常以季度为周期,反馈周期可能需要数周——这种缓慢的循环是达成共识和学习的主要障碍。
这一切都需要能够促进差异化学习的材料。单纯宣扬“我们在谷歌就是这么做的”只是空谈。
这里有一篇文章供参考:https://www.chromium.org/developers/design-documents
> 对软件设计方向存疑,是否值得提前投入时间以明确方向?
这是一个值得探讨的问题。人类天生缺乏远见,尤其在面临截止日期压力时,但从长远来看这能节省大量时间。
>最后,创建和审查设计文档的开销可能与原型设计和快速迭代不兼容。然而,大多数软件项目确实存在已知的问题。采用敏捷方法论不能成为不花时间解决已知问题的借口。
这里是文章最大的问题所在。大多数软件项目_并不_有一系列已知的问题。敏捷开发之所以存在,正是因为很难明确界定问题是什么,而通过逐步实验,你对产品的了解远比通过某种宏大、集中的设计要多。
除非你对解决方案完全确定,否则设计文档在大多数项目中没有存在的必要。
我不同意这种观点。敏捷开发强调的是“及时设计”,而非“无设计”。
在某个阶段,你需要决定接下来要构建的增量内容。在编写该增量的代码之前,你已经明确选择了需要解决的已知问题,因此应该为此编写设计文档。
我认为你反对的是瀑布式开发中那种涵盖整个项目的设计文档,而非仅设计接下来要工作的内容。我完全同意这种反对意见。
然而,文章中提到的内容与史诗级或故事级设计是相容的。随着复杂性和变更成本的增加,更多的前期设计是合适的。这些与敏捷原则中构建小增量并频繁交付以确保其增加价值的理念并不冲突。
如果你有幸在项目早期阶段工作,代码量仅有几千行,且几乎没有生产数据需要维护完整性,那么正式设计文档的价值会大幅降低。但重要的是要明白,你以后会需要它们。
你是否建议每个迭代周期(例如两周)都编写一份设计文档?
在某些迭代周期中,我的团队会编写多份设计文档,尽管这并不常见。例如,如果我们正在开发两个新功能,且每个功能都是独立的。这些设计文档可能比较简短。
在其他迭代中,我们不会编写新的文档,例如当我们正在实现并发布/演示一个大型复杂功能的各个部分时,而这些功能的技术设计已经完成。
我建议将设计文档与用户故事/主题关联,而不是与迭代关联。
虽然我同意,但我认为这种常见的论点存在修辞上的缺陷。领导层往往对“存在他们未知的问题”的指控感到反感。他们对不确定性的怀疑可能表现出明显的防御态度。
我认为可能存在一种更好的方式,来表达快速迭代和边设计边开发的价值,而不会引发对抗性反应。
这是对设计文档非常乐观的描述。另一方面,这些文档可能成为无谓争论的焦点,或成为制作幻灯片而非实际软件的借口。大量行政冗余可能通过设计文档渗透进来。
在中等规模的公司/初创企业中,这种模式运作得非常良好。
比核心平台团队在每次发布时随意更改大量内容却不做文档记录要好得多,我之前的工作中就经常遇到这种情况。
我认为传达此类信息的最佳格式是“展示而非讲述”。请提供一个示例文档,并在旁注中说明每个部分的用途和重要性。
这样我们就能看到它实际效果如何,而不是靠想象。
设计文档应使用Markdown格式编写并存储在Git中。此处的优势在于Git哈希值可作为法律依据,例如在承包商需实现该设计时。
我尝试过这种方法,也尝试过像谷歌员工那样使用Gdocs。Gdocs似乎更适合迭代,因为GitHub的代码审查界面很糟糕(而其他平台更糟糕)。如果谷歌的代码审查系统公开可用,我更倾向于使用Markdown进行设计。
最佳做法是先在Gdocs上达成设计共识,然后将其导出到GitHub,使设计文档与代码并存。
我们在之前的医疗健康领域公司也采用过这种方式。这使得审计变得轻松,因为我们可以追踪每个设计变更的实例、审批人以及实现该变更的代码(所有内容都封装在PR中)。
总体而言,我喜欢将文档提交到源代码控制系统,原因与我们使用Git和代码审查来管理代码本身相同。
区分“设计文档”与“文档”至关重要。简而言之:“应然”与“实然”。
如文章所描述,“设计文档”是一种帮助做出决策的工具。它是一个提案。它是“应当”。它描述了某一时间点的世界状态、期望的变更以及如何实现变更。一旦决策做出且工作开始,它很少会被更新。
“文档”仅仅是“当前状态”(通常指“现在”或“版本x.y发布时”)。它描述了系统的设计和使用方式,但很少涉及系统可能存在的其他实现方式。如果文档链接到设计文档,那么它应该用于
一旦明确这一区分,便可看出设计文档应存放在类似Google Docs的工具中,而文档应存放在类似维基或Git的工具中。设计文档过时是可接受的,但文档过时则是个大问题。等等。
这些文档往往是在事后撰写(或在重大变更后更新),因此常被用作低质量的文档。我原则上不反对这种做法,但尚未真正看到其好处。谚语“在准备战斗时,我发现计划是无用的,但规划是不可或缺的”似乎适用。
设计文档很棒,因为撰写它们符合作者的最佳利益,而不仅仅是未来读者的利益。(这与项目完成后撰写的文档不同。)
设计文档有助于理解项目、识别依赖关系并避免重复工作。它们还为未来工程师留下了代码背后思考过程的痕迹。
太棒了!感谢分享——我觉得这在我工作中可以派上用场。不过我有个疑问……如何分配时间来撰写设计文档?有时可能只需一天,但有时可能需要更长时间,如果需要审核则会耗时更久。我在敏捷/Scrum团队工作——这种工作方式如何融入其中?
阅读这篇文章后,我联想到谷歌的事件追踪(Chrome 追踪)设计文档,非常简洁明了:https://docs.google.com/document/d/1CvAClvFfyA5R-PhYUmn5OOQt…!
这并非设计文档,而是格式规范。它直接跳转到实现细节,未讨论设计动机。读者无法评估示例 JSON 的实用性,因为文档未说明任何用例。
坦白说,谷歌的大多数设计文档确实如此。它们是事后编写的描述,旨在为晋升服务。
是的,你可以通过文档标题是“FooBar 设计文档”,但短链接是“foobarforperf”来判断。
对权衡的强调对我来说是最重要的部分,因为它正式化了对替代方案的搜索。在我大多数设计文档中,我最终会将“替代方案”直接替换到文档中,因为我越来越被替代方案说服。
有没有使用这种格式的优秀文档示例?
写作有助于思考。在创建设计文档的过程中,你会获得思路的清晰度和细节的完善。
我希望能看到一些真实世界的设计文档示例。
由谷歌内部开发的虚拟化工具包Ganeti(作为开源软件发布)中充满了此类设计文档。作为外部Ganeti用户,我一直很享受阅读这些文档:
http://docs.ganeti.org/ganeti/master/html/#implemented-desig…
有点讽刺的是,那篇帖子的作者正是 AMP 的创建者…
我很好奇为什么标题中需要加上“在谷歌”。我非常惊讶地看到有组织在构建东西之前不使用某种设计文档——唯一不同的只是它们的规模和范围。
当然,你不会在HN的首页上看到“亚马逊的设计文档”——出于某种原因。天啊,我真好奇为什么?
> 我会非常惊讶地看到有组织在开发项目前不使用任何形式的设计文档——唯一不同的只是项目规模和范围。
有些公司采用敏捷方法论并摒弃任何形式的设计文档(他们只崇拜能运行的代码,且仅此而已)。我见过团队只是讨论问题,获取一些输入后就开始编写(可运行的)代码并通过测试。设计过程确实存在,但没有文档供任何人参考。可能会有高层次的架构文档,但不是人们通常理解的“设计文档”。
我总是好奇这种方法如何用于构建可维护的软件,尤其是当软件规模不小的时候。即使假设代码经过了单元测试,但如果没有某种设计文档来指导整体结构和交互,难道不会导致难以维护的软件吗?
在我工作的地方,我们可能不会遵循这种方法,仅仅是因为我们不喜欢谷歌产品的设计
谷歌的设计文档文化是我离开公司的原因。
我刚加入公司不久就写了一份非常高层次的文档,概述了一个相当简单的任务(这个任务在其他产品领域已经多次完成)。
一位同事几乎把我拉到一边,告诉我“这不是我们在这里做事的方式”。这对我来说是一个警钟,因为他告诉我一定要“评估更多完成这项任务的方法”,尽管我概述的方法实际上只是推荐方法的微小变体。
当被问及为何需要这样做时,他回答:“这体现了全面考虑。”
“虚假工作”在谷歌确实存在,我真希望当初加入了其他团队。
你鼓励的行为就会得到相应的结果。在“早期阶段”,设计文档是用来达成共识并向同事解释工作方向的工具。后来,随着新员工以指数级速度加入,善意的经理们以性能优化为由要求他们撰写文档,事情从此开始失控。谷歌的文化变成了对自身文化的盲目崇拜。
我之后加入的某些公司不愿详细讨论晋升流程,因为他们目睹了人们为追求晋升而过度优化的后果。
我在谷歌时指导过许多初级工程师,我总是告诉他们要比他们认为需要的更多地撰写文档。有时文档能提前发现问题,但职业早期撰写简单的文档是一种简单的方式来展示独立性和能力。这会拖慢项目进度,但谷歌很可能还是会取消那个项目,我的理论是“谷歌不在乎你,所以关心它只会让你显得愚蠢”。在很多方面,那是一个很棒的工作场所,但它慢慢让我发疯。
这听起来像是你在倡导那种导致谷歌崩溃的心态?
写那些拖慢进度的文档,不要编码/构建项目,这一切都以贪婪为名,唯一的借口是项目迟早会被取消(可能是因为没有真正的工作完成)。
备注:我是谷歌员工。
谷歌存在的一个问题是创建了远超实际需求的产品,导致了著名的“谷歌坟场”。我开始喜欢为自己的想法撰写设计文档的原因之一是,许多想法在写出来后被证明是垃圾。其中不少想法已经有人做过,或者非常接近,我的同事可以告诉我这一点。这是一种非常轻量级的方式来淘汰无用项目。
而且,Reader并不是无用的。那是另一个故事。
文档非常有用。我喜欢它们,尤其是考虑到那里的开发速度有多慢。只是根据我的经验,它们被过度强调了。例如,在已经开始实现某个功能时撰写文档只需一天时间,但对没有上下文的人来说,这看起来比一天的编码工作要好得多。幸运的是,至少在较低级别,他们改为让绩效评估者在组织上更接近,并且经理也在场,所以至少有一点上下文(尽管我的经理通常太忙,以至于他们也不完全知道我在做什么)。有很多具体的要求,基本上是晋升的勾选项,以及在较小程度上是评分,最终我决定还是给他们他们想要的
问题出在公司文化上,公司不希望有一个“无聊”的产品,每年能稳定赚取一定金额(比如1亿美元)。它只希望产品能指数级增长到数十亿美元。
谷歌仍然可以保留那些无聊但盈利的产品。就像微软一样(尽管他们将这些产品捆绑在一起)。
但似乎在谷歌,晋升不是为了那些有效但无聊的事情。
我只是机器上的一颗螺丝钉。这种思维方式并非源于我个人,而是公司内部的激励机制和项目运作方式。说实话,我最终对这种运作方式感到非常不满,而我的建议也基于我试图关心公司和产品的经历(事实上,我正试图完全离开科技行业)。我最终将关心和努力投入到培养同事身上,而不是投入到公司或其产品中,这就是我坚持了一段时间的方式。不同的人有不同的经历(毕竟这是一家大型公司),我所说的任何关于我经历的事情都非常个人化。
编辑:此外,如果谷歌希望我真正关心我的工作,而不仅仅是出于个人利益,那么这种关系需要是双向的。忠诚的员工与漠不关心的公司之间的关系很常见,但在我看来,这显得有些可悲。我在那里做得很好,仅仅是因为这就是我享受工作的方式,如果公司倒闭了,我不会流下一滴眼泪(这是谎言,我怀念免费的食物)
但如果他们最终还是要取消这个项目,我宁愿至少编写代码并进行开发,只是为了享受乐趣,至少能有一个原型,而不是去做那些枯燥的工作。此外,我感觉通过编写文档来进入解决问题的正确心态,远不如实际编写代码时那么有效。
如果他们喜欢编码且不打算优先考虑职业发展,我会建议他们努力寻找自己更感兴趣的项目(或项目部分)来编码,并确保自己能被分配到这些任务。我的建议总是因人而异。问题是,对于大多数初级工程师来说,他们已经编写了足够多的代码(而且代码本身通常并不特别有趣),因此大多数时候的建议是多写文档,因为缺乏文档会影响他们的绩效和晋升,但具体情况因人而异。
如果项目最终注定会被废弃和关闭,也许不如骑一辆谷歌自行车在校园里转转,喝一杯食堂里美味的冰沙。
对我来说最疯狂的是,在我所在的地点,参加免费健身课程的人并不多。在那些课程和食物的帮助下,我在那里工作时处于人生最佳状态。
随着他们不断取消我参与的项目,我的身体状况逐渐变好,但我对实际工作的热情也慢慢消退。我意识到在那里工作对我来说是多么没有意义,但薪水太好,让我不想离开。
编辑:我确实运气不好。我认识一些人,他们参与的项目更稳定。我在不到6年的时间里经历了4个被取消的项目
里面有酒精吗?如果有,我会考虑,但我还是会带上酒精并继续编写项目代码。
为了迎合“ cargo cult ”的信仰而进行微优化,比为了真正获得晋升而进行微优化要糟糕得多。
到了某个阶段,“ cargo cult ”就是晋升评审者,两者变得相同。
评审者理应能够访问真实的考核指标。
如果我告诉你,这些就是他们的“真实考核指标”呢?
如果一家公司没有在各团队中统一采用一致的绩效考核指标,那你应该立即离开那家公司。那只是裙带关系的温床。
请举例说明软件工程绩效评估的指标。
概念性示例(不讨论具体标准):
高级工程师应:
* 设计一个具有可量化客户影响的重大项目
* 在编码之外至少掌握一项核心技能(测试基础设施、SRE、安全、无障碍等)
* 通过担任团队领导(TL)、主导团队核心任务(如安全审查等)等方式展现领导力
* 等。
中级工程师应:
* 独立负责一个小型功能的端到端开发,或参与大型设计中的关键模块
* 参与至少一个非编码核心领域的工作
* 等。
这些要求通常涵盖更多领域,并可进一步细化,例如“表现较差的中级工程师为X,合格为Y,优秀为Z”
这些是要求,而非指标。
同意。
这恰恰证明了这一点,此人只是盲目模仿了近年来让谷歌闻名遐迩的模式。如果你的唯一指标是启动新项目,那你只会启动新项目。谁会因为维护工作而获得晋升?
>概念性示例(不打算就具体标准展开争论)
再次强调,我不是在辩论具体标准应该是什么,只是举例说明你可以使用的指标类型。你更倾向于哪种替代方案?代码行数?还是随老板心情而定?正是这种做法让人们不相信来自本周热门初创公司的“高级员工明星”有多好,并要求他们进行白板展示。
在足够细致的情况下,两者没有区别。我不能引用确切的条款,以免违反保密协议,但类似的条款在我工作过或认识的人工作过的每家大型公司中,都是绩效评估的标准。
你所说的“真实指标”指的是什么?
决定某人是否晋升的指标。这些决策由某个小组做出,想必有相关指南。如果晋升流程是“这个小组随心所欲地决定”,那家公司就是个灾难,你需要尽快离开。
因此,确实存在规则,且这些规则是成文的。如果普通员工无法看到这些规则,他们会根据看到谁被晋升来推测规则( cargo cult ),而委员会则使用真正的指标。
成为经理并不是加入一个秘密组织,让你突然获得无限权力可以为所欲为。在成熟的公司中,有既定的规则和流程,虽然你可能比普通员工获得更多信息,但你不能随意提拔自己喜欢的人,而无需经过他人批准。
无论如何——如果这种微观策略制定占据了你日常工作的全部注意力,那么你显然身处错误的岗位。
我对此不以为然——两者皆不可取。若身处高度复杂且专业化的领域(传统意义上的专业领域),单一维度的优化会掏空整个工艺。工程学是 delicate 的,需要不断权衡取舍,而决策后果往往因平均任期较长而被延迟,更不用说仅有6个月的绩效周期。你越是将流程麦肯锡化,结果就越平庸且缺乏连贯性。
你得到的就是你衡量的。你不能雇佣聪明且有动力的人,然后对他们优化自己的奖励感到惊讶。
如果你想要一个能够推出稳定且受客户喜爱的产品的团队,那就让那成为你的绩效评估。结果证明,要客观且一致地做到这一点是很困难的。
根据你的另一条评论,那么,一家“推出稳定且深受客户喜爱的产品”的公司,就会成为“裙带关系的温床”,人们不应该为这样的公司工作。
胡说八道——你可以制定已知且与绩效挂钩的量化指标。
例如:
* 要求功能在一段时间内发布,而不是在开发中或在绩效评估前一周仓促推出
* 将客户满意度和值班页面指标纳入评估
等等。
在我看来,你很多回复都是胡说八道:),这种“一切都要衡量”的想法在我看来是另一种迷信。软件工程是复杂的,人是复杂的,认为你可以制定一个真正的指标,而没有这个指标的人就不知道自己在做什么,这是在我看来是胡说八道。
让工程师充满热情,给他们良好的报酬,让他们从事与职业发展相符的工作并为客户提供价值,他们其实不需要更多。其余的只是试图将人类行为“流程化”
> 你不能雇佣聪明且有动力的人,然后对他们优化自己的奖励感到惊讶。
我从未说过那句话。我没有解决方案。不过我有一个部分解决方案,但不完整:
根据团队或公司的表现,平等地奖励所有团队成员。例如:蛋糕被分成三部分:公司、团队和个人表现。奖励根据团队和个人的表现发放。
这并不能解决可操纵的指标问题,但当人们合作时,副作用比他们只考虑自己晋升时更好,而当他们与直接同事竞争团队中固定的奖励份额时,副作用更糟。这种激励机制直接阻碍了那些最需要合作的人之间的协作。
这很可能源于负责老旧成熟产品团队所建立的文化。在那里,你需要与至少10人合作推出一个简单项目。以我为例,通常是20~30人,影响范围达100~500人。你不可能与所有人进行一对一沟通,因为大家都很忙。如果你没有得到利益相关者的良好反馈,很有可能会有一些不满的人找你麻烦,迫使你撤回发布。
在这种情况下,设计文档被用作异步沟通工具,用于处理信息量大的主题。这种异步沟通如此彻底,以至于如果你产品非常成功,你可能会在10年后与这些参与者进行沟通。我曾多次因2010年某份随机设计文档中解释的那个至今仍困扰我们的奇怪决策而得救。这可能在精益/小型团队或复杂度较低的任务中效果不佳。但工程文化通常有其自身的逻辑和背景,即使它已演变为一种 cargo culture。
如果某件事只有一种简单直接的实现方式,我们会做“一页文档”;不过,我同意谷歌在这方面的观点。
如果你在设计某物,而只有一个解决方案在考虑范围内,要么根本没有设计,要么你不够彻底。选择和权衡才是设计的核心
如果某件事非常显而易见,且过去20次都采用相同方法,以至于考虑其他方案都显得尴尬,该怎么办?你可以列出这些尴尬的方法,但这仍感觉像是徒劳的展示性工作。
我不想陷入为谷歌式设计文档辩护的泥潭(我对此有……看法),但就这一点而言,有几点想法:
1. 显然,你写这份文档是为了让其他人阅读。对你来说显而易见的事情,对他们来说可能并不明显。
2. 如果你没有“考虑过其他方案”,这表明你确实没有考虑过其他方案。我曾多次遇到“这很明显,而且我们一直都是这么做的”这种说法,结果却让我走上了错误的道路。花几分钟时间思考“显而易见”是否等于“正确”,并写下原因,从长远来看并非一项糟糕的投资。
3. 我只能代表我自己说话,但我并不喜欢被批评,也不喜欢犯错。“考虑的替代方案”通常放在文档的最后,我常常想跳过这一部分,因为有很大的可能性,当我解释为什么不选择方案B时,会意识到方案B比我花了很多时间制定的计划更好。
9/10的情况下,这一部分很短很简单,但出于上述原因,它仍然是一个值得做的练习。解释“什么都不做”的替代方案是强化你所提议方案的成本效益的好方法,而且通常很容易设身处地为他人着想,想想他们脑海中第一个浮现的“为什么不直接……”的问题。写下“因为它无法扩展”,你就省去了那段对话。(开玩笑。也许。)
> 我只能代表我自己说话,但我并不喜欢被批评,也不喜欢被证明是错的。
这实际上是一个大问题,因为它可能导致学术不诚实和无端争执。相反,应该努力寻找正确/最佳的前进方向,无论之前的想法如何。应该很容易放弃错误的想法。
目标不是要正确,而是要找到正确的事物。
我有一位睿智的朋友告诉我,工程师总是处于错误的状态。你今天建造的东西,五年后你很可能会嘲笑它。今天的目标是建造最不错误的东西。我过去常常争论得比应该的更多,仅仅是因为我也不喜欢被证明是错误的。听到这些后,我变得更加客观。
我的问题是,我所知道的最不错误的东西与现有流程大不相同,而且需要更多时间和金钱,而大多数人无法接受。
时间和金钱也是错误的因素。这就是软件工程与计算机科学的区别。
确实,但还有更糟糕的情况,比如“在事件驱动系统中使用专为数据分析设计的查询语言来读取、解析、版本控制和写入系统及配置文件,而非使用Git等版本控制系统”,以及负责该系统的销售/市场营销人员犯的错误。
时间以季度为单位衡量,资金则模糊地以销售额为依据。
认为使用Excel作为数据库很糟糕?试试在这样一个系统中工作:字符串在SQL中被`eval`执行,每次状态变化都存储在中间或虚拟表中,然后被丢弃,因此实际上没有版本控制;只是在比较和合并Unix配置文件。
为什么不使用diff和patch?太耗时耗资,他们只懂SQL。
>目标不是要正确,而是要找到正确的方法。
这就是为什么我认为设计文档需要轻量级且尽早审查。设计文档不应是经过数天或数周孤立完善的大作。这保证了作者的观点已固化。在我参与亚马逊的审查小组时,99%的审查都是徒劳的——作者早已定案。避免“哼!我比任何人都更深入地思考过这个问题”的思维陷阱,这种陷阱源于沉浸在“做设计”的孤立世界中。
越早让其他人参与进来,人们就越有可能真正听取反馈并考虑替代方案。当然,你仍然需要专注的时间来完善所有细节,但设计的大致框架不应在设计审查时才首次揭晓。
我认为过度依赖委员会决策也存在风险。根据我的经验,许多随意反馈者实际上并未充分思考问题,因此无法理解其即兴反馈或替代方案为何不合理。若此类建议被采纳,可能只会增加设计流程的混乱度。
很好的评论。我认为你们两者的观点都合理,且体现在设计规模上。
也就是说,如果有人设计一个庞大的端到端系统,外部人员要识别设计中的潜在缺陷将非常困难。因为其中包含大量相互关联的部件,需要在脑海中构建完整的 mental model。因此,应分步进行。
确实,并非所有反馈都具有同等价值,因此提前考虑如何应对反驳意见至关重要。因为大多数人不会提供深入的反馈,而是基于直觉的表面感受(尽管这种反馈也可能非常宝贵,即使仅仅从用户体验的角度来看),除非他们之前曾思考过如何解决相同的问题。这需要花更多时间来思考设计。
完全同意。将早期设计想法(非正式地)与其他利益相关者或至少更经验丰富的工程师讨论,可以节省大量麻烦。反之亦然:对他人设计提供早期反馈,可以让他们获得所需的洞察力,从而避免给你带来麻烦。
那么这只是一个变更,并通过常规代码审查进行审核。设计文档仅用于处理那些不明显的情况。
那你不会得到晋升吗?
在你的情境下也不会得到晋升。对于一些琐碎的事情,设计文档会在晋升材料审查中被指出,且不会被重视。如果晋升材料主要由这类文档组成,晋升申请将被拒绝。
这取决于级别。对于初级工程师来说,这些设计文档很棒,因为它们可以教育其他初级工程师关于工程知识,教育高级工程师关于良好的文档写作,并展示在文档写作艺术上的发展技能,在工程师承担撰写更复杂内容的认知负担之前。
做好不值得撰写文档的工作 => 获得值得撰写文档的工作 => 撰写文档 => 获得晋升
嗯……大多数时候,当我设计一个有一定分量的东西时,我通常会先经过几个在“草图阶段”看起来合理的想法,然后放弃它们,转而采用最终成为“正式设计”的方案。我会保留这些草图,在“替代方案”部分列出它们,并解释为什么放弃它们。很简单。
这就是想法。我尽量让文档中花在每个想法上的时间与该想法的可行性成正比。
这样就会轻松快捷,而且一点也不尴尬。
我在工作的地方遇到相反的问题。当我要求人们为一个相当简单的任务撰写一个非常高层次的设计文档时,他们会说:“有很多其他方法可以完成这个任务,所以撰写这些文档是没有用的。而且,既然任务很简单,工程师应该能够想出其中一种方法并完成它。”
其中许多人是与公司合作超过15年的外部顾问。因此,已经建立了一套合理的标准,因为这些任务一直由同一批人完成。但他们却刻意制造“如果人们不遵循标准会发生什么”的恐慌。
最终结果是,要么设计文档不存在,要么严重过时。因此,公司不得不年复一年地以高昂的成本聘请这些顾问。
> 因此,公司不得不年复一年地以高昂的成本聘请这些顾问。
问题就在这里。拖延问题可以带来可观的利益。
过去在其他团队也曾有过这种感觉。几乎就像是被要求为了写而写( cargo cult engineering)。
现在在一个由许多元老级谷歌员工(15年以上工龄)组成的团队中,设计文档只在需要时存在(涉及多个系统、明显复杂且存在诸多权衡取舍的情况等)。否则就是“写 CLS”。
> 现在我所在的团队中有许多资深谷歌员工(任职15年以上),设计文档只在需要时才存在
这几乎肯定与团队或任职年限无关,而与他们试图晋升的职位级别有关。你是否控制了这个变量后仍然看到差异?
在这些简单的CL案例中,假设系统已有文档,新代码遵循设计规范。
(抱歉提出新手问题)但在此情境下,CLS指的是什么?
变更列表(拉取请求、变更集)
这并非谷歌独有。优步和爱彼迎也鼓励此类做法。我认为这是常见做法。目的是展示你考虑了替代方案并进行了尽职调查。一味遵循既定做法未必是好事。若涉及不同产品领域,可能存在更适合该领域的独特方法。这并非虚假工作,只是证明你确实考虑了其他方案而非盲目遵循现状。
您说得有道理,官僚主义确实可能无端阻碍有意义的变革。坦白说,这种情况在一定程度上总是会存在的。不过,确保官僚主义对变革的阻碍降到最低的一种方式,就是对其进行标准化,并严格执行这些标准。
从您的描述来看,您同时属于这两类情况,这意味着您的同事是正确的。然而,你提供的细节非常有限,因此我很有可能对情况有所误解。但从企业层面或变革管理角度来看,如果你允许成千上万的员工在某些地方有轻微的偏差,那么你很快就会得到相当于意大利语、西班牙语和法语之间差异的结果。这些语言都基于相同的拉丁语“标准”,然后只是略有不同。
如果你认为管理执行设计文档标准的官僚主义流程涉及大量形式主义工作,那么你应该看看这样做能节省多少形式主义工作。
我并不反对,因此用引号标注了“虚假工作”。
有些人可能(而且显然在这种环境中茁壮成长),但我个人并非如此。
这个特定场景是一个简化的摘录,但非常准确地捕捉了我所经历的感受。为一个已经由维护框架的团队解决的问题编写设计文档,感觉就像是纯粹的无意义工作。
如果这个过程有更高的意义,那么这种意义(除了看起来不错/获得晋升)并没有以任何有效的方式传达出来。
也许我对大型科技公司的当前文化感到失望,但晋升应该是有益工作的结果,而不是做那些看起来不错的工作。
是的,我明白这些机制可能存在,以帮助员工更清楚地看到晋升的道路。
优秀的工作需要看起来出色才能被认可。而在企业中,它需要能够被比较,以确保公平并实现自上而下的控制。
标准解决了这些问题,但代价是某些开销和浪费,因为它们本质上是最佳实践的泛化体现(至多如此)。
尽管一些开销是游戏的一部分,但标准(和指标)的有效性确实有所不同。并非所有标准都具有同等价值。听起来谷歌的一些标准确实有些偏离正轨。
我也不太喜欢这种做法。尤其是因为我从未见过太多所谓的“虚假工作”能带来多少价值。通常,企业架构(或无论你如何称呼它)最终会变成大量过时的文档,这些文档因从未更新而变得毫无用处,尽管初衷是好的。随着时间的推移,随着领导这些努力的人员变化,他们的标准偏好也会随之改变,从而侵蚀其自身的标准。
最后但同样重要的是,让实际的开发人员去做这件事完全是在浪费时间。他们本可以做些有用的事情。当然,挑战在于,90%的架构师和相关人员实际上不知道如何根据变化编写自己的设计文档,这意味着他们需要浪费开发人员的时间来完成……这意味着他们不仅是完全无用的员工,还在浪费无用员工的时间。
这不应被视为非黑即白。如我之前所写,这可以用来帮助工作流程。只是在现实中,这些流程通常会造成远大于益处的危害。但如果你一定要做,至少强制执行标准是正确的做法。
我个人避免在官僚主义过于严重的场所工作,因为我不想浪费时间撰写那些在获得批准后无人阅读的文档。
听到你的团队是这样,我感到遗憾。我的团队则采取了“既然你知道如何解决问题,何必费心撰写设计文档?”的态度,我从未因此感到负担。
> 你说得对,官僚主义确实会无端阻碍有意义的变革。
一份好的早期设计文档能将无意义的变更(例如为了宣传而做项目)转化为有意义的非变更或最小化变更。最好的代码就是无需编写的代码。
至少在我所在的领域(核心),设计文档只有在涉及需要数年时间或多名工程师参与的大型项目时,才会经历类似正式流程。其他领域可能有所不同。
你说的有道理,但前提是他们没有强迫作者去寻找更多替代方案。
那么可以引入其他领域的模板,指出重复的工作。你不能只是在简要说明中交给开发人员几行代码,尤其是当他们不知道之前已经做过类似工作时。
错误在于制作设计文档而非直接编写代码。如果问题足够简单,无需讨论,通常直接修改代码即可。如果问题足够复杂,就会演变成一个谈判过程,至少需要5个不同的人能够将其纳入自己的工作范围,才能完成任务。
大型科技公司的薪酬结构会让人们为了下一轮晋升或股票期权而疯狂优化。这种机制有助于大型科技公司留住人才,但追求“有影响力的”表现所带来的激励却会导致错误的行为。
解决这个问题的老办法是为常规工作设立一个固定的变更订单,这样你可以指着它说“我的问题就和这个一样”,然后立即获得批准。不过,一旦你提出像变更控制这样的建议,人们现在都会变得很奇怪。
对。
> 是否编写设计文档的决策,本质上是权衡组织在设计共识、文档记录、高层审核等方面的收益,是否大于创建文档的额外工作量
我认为创建文档的额外工作量是优势,因为它能清晰化你的思维过程,而委员会式设计则是巨大劣势。
事实上,我正在参加一次设计文档会议。我从这次会议中一无所获。我一上午都在写代码,而现在的背景噪音让我无法继续高效工作。
这类事情的问题在于,它会耗尽团队的(有限)精力。并非每个人都是坦克。高智商的人一旦失去生命值,就会耗尽所有法力值。
我现在正在另一家大型公司处理类似问题。被要求为一个我们已经做过20多次的集成项目撰写文档,因为这是别人更大推广项目设计的一部分。
难道不能直接引用最近的文档,说这基本上和之前一样,只是有x个差异导致了y个改动,出于z个原因?
我最近采访了几位谷歌员工,他们的工作方式令人震惊,这非常不幸。我为那些在谷歌工作了一辈子的人感到惋惜(例如:过去5年内从应届毕业生开始工作的人),他们很可能并不真正懂得编程。
设计文档的另一个说法是“货架软件”
我感觉在谷歌,设计文档的问题在于它们是晋升材料的主要内容,这导致撰写时更多考虑晋升委员会的意见,而非文档本应面向的实际系统开发人员。
我之前任职的每家公司都如此。职业发展更多取决于曝光度,而非声誉或能力。设计文档对上级管理者非常显眼。每次加入新公司,我都会提议开始撰写设计文档。这立即让我在管理层中获得好评 🙂
这导致许多文档采用更复杂的设计模式,而实际上完全没有必要。这一切只是为了从那些只匆匆浏览文档的人那里获得更多的“绩效积分”。
我读过许多文档,在我看来,这些文档显然是在文档开始撰写时就已经做出了决定,并展示了我们已经想要的东西,同时提出了2个以上的愚蠢替代方案(至少一个过于简单,另一个是毫无必要的过度设计),然后将它们进行对比,选择一个合理的方案。
开发人员直言不讳地告诉你,他们撰写设计文档是为了促销委员会。这是他们的目标,其他一切都是次要的。由于他们从未知道哪些设计文档会被用于促销包,因此无论项目大小,他们都会将所有工作内容纳入设计文档。虽然有“一页纸设计文档”的概念,但通常这些文档会从一页扩展到……多页。即使是一个为期一周的项目,也会撰写设计文档。我曾审核过20页、30页,甚至40页的设计文档,这些文档显然耗费了大量时间制作,而在其他公司这可能只是一个JIRA工单。我们曾讨论过多少页算太多,是否应设定页数限制等问题。
太多人(无论正确与否)认为,评审委员会只希望看到文档由作者单独撰写,而没有其他人参与。这进一步拖慢了整个流程,并削弱了跨部门学习的动力。我认识一些软件工程师,他们会花一个季度甚至更长时间独自撰写设计文档。设计文档中99%的内容是问题定义,而实际设计部分仅占1%。我多次在审查过程中花费大量时间改进问题定义,结果导致设计方案需要推翻,大部分文档也需重新撰写。
最糟糕的情况是,通过改进问题定义,一个简单的解决方案浮出水面,而无需复杂的设计。作者在复杂设计上投入了大量时间(这种设计在历史上以及许多委员会中仍然被视为推广的对象),因此会对任何简单的解决方案提出反对。关键在于如何在写作初期帮助工程师改进问题定义。
我见过一些设计文档中没有提供任何替代方案。这些设计文档只是以耗时的方式记录了需要完成的工作或某人想做的事情。
这也会导致设计文档在某种程度上变成一个缺陷跟踪系统。以一种模糊的方式,每个人都在专注于自己的设计文档,而不是缺陷,因为缺陷不会让你得到晋升。
而 OP 喜欢诗意地描述,当你加入一个团队时,你可以直接查看设计文档,就像这是一件简单明了的事情。但这些文档往往没有在任何中央位置进行跟踪。对于许多团队来说,设计文档不是由团队或项目所有,而是由个人所有,因为你可以确保没有人 else 贡献。这是为了晋升委员会的利益。许多设计文档你无法访问,不是因为它们是绝密文件,而是因为其他原因。而且团队并不是只有两三个设计文档,而是有一大堆设计文档需要阅读。由于谷歌大约每两年就会进行一次人员更迭,许多设计文档都会随着时间的推移而丢失。在其他公司,这可能就像你加入团队后,我告诉你所有需要的资料都可以通过阅读所有已关闭的 bug 或查看主分支中的每条提交信息来获取。
在其他地方,我会在午餐后被叫去,与团队在白板上花几个小时定义问题。资深成员会实时指导新人如何思考这些问题并快速迭代。大多数情况下,这些内容会被记录在 bug 跟踪系统中,或者对于更重要的内容,会被记录在项目维基或文件夹中,供所有人查看。
以上所有内容都可以改进,我也一直在努力改进这些内容,但文化变革是一个缓慢的过程。设计文档作为一个概念是好的,但其中存在陷阱,而谷歌许多人(并非所有人!)使用设计文档的方式并不理想。
> 最糟糕的情况是,通过改进问题定义,出现了一个无需复杂设计即可实现的简单解决方案。而作者已投入大量时间在复杂设计上(这种设计在历史上和许多委员会中仍被视为推广对象),因此会抵制任何简单方案。关键在于帮助工程师在写作初期就改进问题定义。
最糟糕的情况是,当更多时间被用于编码、测试、发布和集成过于复杂的设计后,再要消除它还需要额外的工作。
> 在其他地方,我会在午餐后被叫去,与团队在白板上花几个小时定义问题。
我在谷歌经常这样做,通常与撰写文档同时进行。没有什么比直接与经验丰富的工程师交流更有效。
此外,还需遵守官僚主义要求。以及对他人文档进行评论,以“展示领导力”。
我渴望看到设计文档的价值能超过其成本。
我不确定区别在哪里,除了提供比团队成员需要的更多背景信息,或试图让问题比实际更复杂。
总体而言,我没注意到这种策略有效。
另一方面,为了提供背景,人们会撰写大量文档,描述团队过去和现在的工作内容、存在的问题等,而这些文档往往冗长且夸张。
我与作者的经历不同,作为在提及公司工作的员工。
设计文档的类型多种多样,但没有一种是有用的。我在谷歌很少见过有用的设计文档。我认为设计文档是为那些过于注重流程的工程师准备的。
以下是我在实际工作中遇到的设计文档类型:
* 宣传型设计文档:它并非真正解释要解决什么问题,而是更多地宣称这个项目很棒,能让公司更好。逻辑结论是,撰写这份文档的人应该得到晋升。
* 技术术语堆砌型设计文档[1]:这种文档充斥着从未见过的专业术语,除非你是团队的高级成员,否则难以理解。有时我甚至不确定团队的高级成员是否真正理解它……
* 新人设计文档:这是一份毫无实质内容的设计文档,但作为刚从大学毕业的人,他们觉得有必要把它写得尽可能长,以证明……我也不知道是为了什么……这份文档并没有传达任何信息。他们很可能复制粘贴了大量已经写好的代码,用来填充文档中大约70页的内容。
* 虚构事实的设计文档:这是一份充斥着“大家都知道”“大家都这么说”的设计文档。当然,它不像某些政客那样明目张胆。但该文档会以“这符合良好实践”“该软件运行缓慢,因此……”等理由推进设计。谁定义了“良好实践”?为什么这是良好实践?什么是慢?是否经过测量?是最终用户的感受吗?
这是我见过的99%的设计文档。当然,也有例外,但在我看来非常罕见。我对作者推动这种做法感到震惊…… 但再次强调,他们并非工程师,而是总监。我猜设计文档对他们的职位有意义,但我仍在试图弄清楚这些人能带来什么价值。
[1] https://en.wikipedia.org/wiki/Turbo_encabulator
那一定变了。我从2006年到2014年在那里工作,当时大多数设计文档都很有用,并且遵循了文章中描述的基本结构(不包括系统上下文图)。
不过我早些时候就注意到,保存在Google Docs中的设计文档通常质量低于保存在版本控制仓库中的文档。不确定这是否只是反映了文档的撰写时间,还是代码审查流程比在Docs中编辑更严格,但唯一一次我撰写了一份较大的(约40页?)设计文档时,我是使用手写HTML完成的,并通过传统的代码审查系统进行审核。我还将其发布到中央邮件列表和网页服务器,并收到了员工编号3的反馈,这很不错。中央位置使查找文档变得容易,因为它们按类别排序。
然而,我记得设计文档的重要性不足以单独决定晋升。晋升应该基于整体影响,而不是特定成果的产出。当然,系统存在严重缺陷,经常做出令人惊讶的糟糕决策,但我记得当时从未读过明显为性能优化而设计的设计文档。
如果你能找到早期用HTML手写的设计文档网站,可以浏览一些,看看是否觉得它们更有用(或在系统处于活跃阶段时会觉得有用)。其中一些旧文档,如SmartASS,充满了对底层方程和模型的详细解释,这对于理解其工作原理以及解释为何选择这些方法非常有帮助。阅读这些文档对我的后续设计工作有所启发。我不是主管,只是工程师,但这些文档确实有所帮助。
Chromium.org网站上还链接了一些Chrome的设计文档,我过去在理解其设计时也觉得很有帮助。
> 不过我记得设计文档本身并不重要到足以成为晋升的依据。晋升应该基于整体影响,而非特定成果的产出。
如何向一个不了解你工作的委员会证明“影响”,而不提供文档、代码示例和其他成果作为证据?
流量,收入。
这忽略了许多不直接影响这两者的工作。
是的,任何以“影响”为奖励的激励系统最常见的抱怨是,对于某些类型的岗位,很难证明影响。我最初从事SRE(“DevOps”),后来转到反垃圾邮件和安全领域,因此不得不寻找其他方式来证明影响。
不过,这种直觉是显而易见的。如果不将激励与对业务的可验证影响挂钩,很多人就会做一些无意义的工作,其中工作的表象取代了实际的有用性。正如这个更广泛的讨论所抱怨的那样。
这种抱怨在任何开发软件的企业中都很常见,即重构或“技术债务”类的工作难以通过业务导向的指标来证明其价值。这种说法有一定道理,但我逐渐意识到,迫使人们找到某种与业务相关的指标来衡量其影响,有助于保持工程师的诚信。何时承担技术债务、何时偿还技术债务,是工程师在晋升过程中需要学习的最复杂和困难的课题之一,而对重构的过度迷恋则是其中最常见的失败模式。提出“但这实际上如何影响业务”的问题,能迫使人们进行现实检验,从而避免陷入注定失败的重写或其他病态情况。
例如,谷歌有一个系统可以自动查找并删除无用代码。这种事情乍一看似乎难以 justify,但只要花点功夫就能做到。计算每行代码的维护总成本(一些粗略的估算即可),计算你可以删除的代码量,计算开发自动删除系统的成本,证明用于维护死代码的成本大于开发系统的成本。业务影响已得到证明,完成。
它也不一定是金钱的。我从未证明过金钱影响。都是诸如“为X的发布做出了贡献,使流量增加了Y”之类的事情。在安全和反垃圾邮件工作中,则是“成功阻止了针对我们用户的Z次攻击”,类似这样的事情。即使不以美元形式表达,影响也是显而易见的。
当初级角色相对于高级角色数量较多时,我见过设计文档发挥作用。这迫使初级开发者提前思考解决方案并为决策提供依据,同时允许高级开发者验证这些决策并异步提供反馈。
当然,我从未在拥有超过30-40名工程师的组织工作过,因为我一直都在初创公司工作。我相信大型科技公司的情况不同,但我对设计文档的经验是积极的。
需要时间和精力确保初级文档的完整性。根据我的经验,通常需要多次修订。这需要管理层认可“只快速编写代码”并非成功路径。
没错!不过我觉得你漏了一个,那就是“请让我直接开始编码”的文档。
我认为技术文档(设计文档或简短文档)的用途很简单。如果你发现自己无法同时记住项目中的每一个细节,那么你就应该写一份文档。同样,如果向另一位工程师解释某个问题需要很长时间(至少30分钟),那么你就应该写一份文档,以节省自己的时间。
我不知道你怎么会认为自己永远不需要写文档
我的经验是,第二种情况意味着“我需要向团队/团队领导沟通我正在做的事情/如何解决这个问题”。最终,当你申请晋升时,你会将第二类文档拿出来,并为它们添加足够的背景信息,使其成为第一类文档。
听起来这些文件没有良好的审核流程;如果它们缺乏实质内容或过于冗长,就不应发布。但我想负责撰写这些文件的人也应获得相应好处?
确实有审核流程,但“是的,你的评论有道理,但只是在挑刺,你能批准它让我们开始这个项目吗?”
这种情况下,当人们互相评审时,可能会觉得为了更容易获得晋升而对彼此宽容,尤其是如果双方都认为这份文档只是为了获得晋升而做的形式主义。
我应该在这里成为一个挑剔的人,找出文档中的每一个瑕疵,还是应该放行,让对方获得更多曝光,然后继续我的工作?为什么我要在这里成为一个无谓的障碍?
说得对,哈哈。
促销设计文档直接由经理们激励:“如果你只是看到一堆CL,那无法讲述一个故事。你需要将其整理成一个连贯的叙述,并让一些>L5级别的员工进行评论。” “这不是给我看的,而是给委员会看的——他们不熟悉你的工作,所以你需要解释清楚。”
> 但他们不是工程师,而是总监,我想设计文档对他们的职位有意义
是的,我认为这只是中层管理[1] 权力斗争中的高杀伤力武器。就连产品经理也不太在意设计文档。
[1]:宽松定义:任何在日常交流中使用“跨职能”一词的人,无论其实际职位头衔如何。
> 设计文档的类型多种多样,但没有一种是有用的。
我主要将它们作为工具来获得上级关注。我尽量让它们看起来尽可能华丽,以让上级认为我是“领导材料”。我一直在用ChatGPT重新撰写它们,用更华丽的语言表达。
如果你是谷歌员工,你应该使用Bard。
我正在努力晋升,而不是被解雇
红布对公牛:“这是最佳实践”。真的吗?在更多上下文或经验的情况下,就没有更好的方法了吗?更好的实践永远不会被发现或设计出来吗?
文档总体上是好的,但我认为这种方法有缺陷:
这些是软件系统或应用程序的主要作者在开始编码项目之前创建的相对非正式的文档。
“在他们开始编码项目之前”。设计本身就是编码项目,两者本质上是同一件事。认为可以在编写任何代码之前在纸上完成设计的想法是错误的。(事实上,设计文档的方法承认需要提前编写一些代码,但试图严格将其划分为“展示设计可实现性的原型”。)
设计文档的一个重要特点是,它为人们提供了在正式编码开始前挑剔细节的借口,即所谓的“审查”。根据我的经验,这通常意味着文档会被添加越来越多的限制条件和对无意义替代方案的讨论,最终可能不再是一份“设计文档”,而更像是一份“请让我开始构建这个东西”的文档。
在存在需要改变方向的重大架构问题时,更好的解决方式是提前与相关人员沟通并协作,而非先撰写详细设计文档再被否决。
若更贴近“相对非正式文档”的理念,并在开发过程中持续维护文档,这实际上很有用,因为它既能产出有用文档,又能构建可工作的系统。但这更像是“将文档编写作为持续协作过程的一部分”,而非传统的“设计文档”。
如果项目足够庞大且经过充分规划,架构变更相对于整体而言无需额外投入太多工作即可融入。
如果
没有人会认为考虑不周的设计文档是好事。要让文档有用,它必须真正做好。
我指的是整体系统,而非设计文档本身中的系统变更。系统的新增部分至少有一点控制权。
啊,是的,那里的控制权确实更少,哈哈。
我是谷歌员工。我以前很讨厌写设计文档,尽管我发表过多篇论文。但几年前我意识到对我来说的主要好处:
* 它清空了我脑海中关于想法的即时部分,让我能够继续深入思考更具生产力的内容。
* 它让缺陷更加明显,尤其是对我自己来说。
* 它让分享这些想法变得更容易,尤其是与其他办公室的人分享。他们通常会给出非常好的反馈。
* 它让我对所需的工作量有更清晰的认识,而不是直接开始编码。
* 它通常会指出我在开始编码前需要学习的一些内容——相关系统、合适的技术选择等。
是的,它也有助于宣传,但成功的项目更重要。
我经常收到关于我的文档有多么有用的评论,所以我认为我做对了。
我也是这样。我发现设计文档最大的受益者是我的思考过程(前谷歌员工)
它有效吗?比其他方法更好吗?讨论在哪里?
我在亚马逊工作过,他们的设计文档文化令人惊叹。我下一份工作所在的公司(我认为)借鉴了谷歌的工程文化(或者可能是旧金山的创业文化?),而他们的设计文档流程则是一个毫无意义的笑话。
设计文档是讨论的工具。其核心理念是,这是传达你的意图、动机以及为何不选择其他方案的最有效方式。
它们是更广泛工作文化中的一种机制。如果你是单打独斗,这是一种奢侈的练习。如果你在大型团队中,它将有助于利用团队中的更多专业知识并作为文档。
存在几种不同的失败模式。
* 重视输出而非结果是典型的目标不一致。(撰写40页的宣传文档——这除了对那些需要证明自己能串联文字而非深入工程能力的初级人员外,通常行不通)
* 如前所述,这对单人团队而言过于繁琐。其他小型团队可通过问题跟踪系统(如Jira)加上头脑风暴会议来有效沟通想法。
* 工程师也需要接受有效设计文档撰写的培训。(注意一位顶级评论者因首次努力未立即获得赞誉而感到沮丧,这可能是一个警示信号。)
撰写关于代码的内容很困难。通常这在HN上被视为一种值得称赞的练习。如果你在团队中,要警惕如果发现你的工作总是无需在可共享文档中详细解释和深入考虑的那部分。
它们是否具有价值取决于人们对它们的反应。如果这一切只是作为一种“仪式”进行,那么它是愚蠢的。如果它是因为组织对如何做出决策和优先分配资源有真正的批判性思考而进行的,那么它是具有价值的。
你最喜欢亚马逊设计文档文化中的哪个方面?
这在智力上是多么严肃的事情。对文档的处理是他们对待工程的一般方式的延伸,而这种方式是严肃而批判的。在大多数情况下,良好的工程实践优先于政治、宣传材料和闪亮的新事物,这与许多公司的情况大不相同。
(免责声明:这非常依赖于组织,因为所有关于亚马逊的陈述都是如此。)
如果一位大投资者乔装打扮,花几周时间以谷歌工程师的身份工作,他很快就会成为要求桑达尔下台的激进投资者。由于谷歌的设计文档文化,浪费的人力潜能之大几乎难以想象。
我认为人们严重高估了大多数设计文档所需的努力。大多数开发工作只是自然发生,偶尔会草草写一份文档以方便为代码更改(CL)辩护。
也许每十个案例中会有一个是过度投入的,但这对普通软件工程师来说真的不是时间杀手。
卡尔·伊坎就是那个合适的人选。https://www.bloomberglinea.com/english/i-fired-12-floors-of-…
读完那篇文章后,再看看社交媒体链接,当然,Twitter现在已经被X取代了(说实话,这是我能想到的最快最有效的品牌重塑之一。向X(原名Twitter)团队致敬,他们做得如此出色)。
我的理论是,晚期的谷歌设计旨在隐藏垄断利润。
这就是如果我想尽可能多地烧钱,我会如何设计一家公司。
设计文档的文化倾向于迫使每个人为自己的工作提供理由。即使这种文化是由同行强化形成的,它对创新者来说也是一种相当压抑的模式。
这种系统倾向于阻止具有远见卓识的努力和抱负项目,因为非共识导向的努力会被扼杀,而“跳出既定规范”的思考方式会让你受到集体的惩罚。
这种系统滋生群体思维,而“我们做事的方式”这种传统导向的性质本质上会强制执行,使得做任何其他事情都可能对你的职业生涯构成威胁。
硅谷各类公司文化往往以“敏捷”和“设计思维”等术语包装的陈词滥调为依托,本质上是将制度化包装成“正确方式”,通常还伴随着对校园内形成的各种“工程文化”变种的社会强制执行。
我无法告诉你有多少人因为谷歌限制了他们的职业发展而离开,即使他们在那工作时感到非常舒适。人数不少。
“我无法告诉你有多少人因为谷歌限制了他们的职业发展而离开,即使他们在那里的工作环境非常舒适。”
这就是为什么他们支付如此高的薪水。这是一个陷阱。还有,在那里工作的“地位”(现在大多已经消失)
你准确地表达了我对在那里经历的挫败感。但我真希望我能拿回那份薪水……
关于“敏捷”我大约20年前以极端编程(eXtreme Programming)的形式接触了“敏捷”,而它与如今的SCRUM或其模仿者所代表的“ cargo cult ”完全不同。归根结底,它是一套原则,旨在将创造力交到开发人员手中,让他们能够“完成任务”,而无需管理层干预具体实现方式——但作为交换,客户获得了决定“做什么”以及(在一定程度上)“何时做”的权力。开发人员自行估算。 “你不需要它”。没有大型的“前期设计”。重构和测试、架构和设计被视为标准的最佳实践,而非独立的故事或任务。规划会议是同事们在房间里讨论问题,而“故事”是白板上用简洁、非技术性语言表达的便签。站立会议就是人们围成一圈进行非常简短的更新,以防其他人感兴趣,而不是为了证明你今天参加了工作,或炫耀。
在这个系统中,设计是创意专家团队协作的自然产物。它并不排除设计文档,仍然涉及架构讨论。但它不需要明确的PRD/设计文档流程。
我多么希望能在这样的团队中工作。我可以告诉你,谷歌完全相反。一切都耗时良久。
> 这就是为什么他们支付如此高薪。
啊,啊,啊。这就是为什么他们支付如此高薪到目前为止。
是的,我离开时(1年前)裁员潮尚未开始。当时已隐约感到GSU更新不会像以往那样慷慨,绩效考核也会更加严格。
我早在裁员开始前一年就预测到了。
这就是为什么谷歌根本无法开发产品。昨天我的新Pixel 7就坏了。所有这些假装“我们很聪明”的行为也是一种无意义的工作。公司应该专注于并评估自己实际可用的产品。
不过,谷歌确实擅长打造真正重要的产品。广告和搜索。尤其是前者。谷歌的广告投放基础设施庞大且稳定,能带来巨额利润。其他一切都是配角。
谷歌真正高质量的工作是由SRE(站点可靠性工程师)而非SWE(软件工程师)在广告/搜索及核心业务部门完成的。他们构建和维护的基础设施令人惊叹,且难以向外部人员解释。我作为前SWE在此亲身经历过。
谷歌搜索功能已持续恶化超过5年,且毫无改善迹象,广告投放位置或许略有优化。
另一位谷歌员工在此。
已有许多评论描述了谷歌设计文档的无用性。我想补充一个我认为存在的问题。
如前所述,设计文档是“宣传”材料,导致大量冗余内容。但它们似乎还取代了实际文档!
每份设计文档在完成的那一刻起就已过时,但团队却引用它们而非编写文档。结果……谷歌的文档质量糟糕且过时。
说实话,我更希望文档/说明是宣传材料,而不是花20页篇幅描述“你没有做的事情”。只需用2页篇幅说明如何使用现有功能
我们能看到一些真实的文档吗?软件设计过程文档似乎是最高机密,因为我从未见过可用于案例研究的真实文档。
Chromium: https://www.chromium.org/developers/design-documents/
Kubernetes:https://github.com/kubernetes/enhancements/tree/master/keps
感谢这些链接!
我随机挑选了一个链接,只是想验证一下我的怀疑态度是否合理:https://github.com/kubernetes/enhancements/tree/master/keps/…
– 好吧,这实际上是一份非常有用且实用的文档!
– 然而,这并非一份前期设计文档,显然是在大部分工作完成后撰写的,旨在解释并为推出重大变更提供依据。(参见“实施历史”时间线:https://github.com/kubernetes/enhancements/tree/master/keps/…)
– 看来这个模板并不实用;大多数必填部分都标记为“不适用”,还有诸如“对于此类工作,最好的测试标准基本上就是‘是否有效?’”之类的评论。
> 然而,这并非一份前期设计文档,显然是在大部分工作完成后撰写,旨在解释并为推出重大变更提供依据。
帕纳斯风格![0]
[0] 《理性设计过程:如何及为何进行模拟》,帕纳斯、克莱门茨,https://users.ece.utexas.edu/~perry/education/SE-Intro/fakei…
嗯,我之前没读过这篇论文,但它太棒了!我之前从未见过如此清晰的阐述,但没错,“伪造”设计文档正是实际操作中发生的事情,而且这是件好事!因为我们需要的是现在就有用的设计文档,而不是过时的历史遗物。
谷歌是一家拥有约18万员工的巨型公司。有时人们会做出明智的决定。
当然!他们拥有数以千计的顶尖开发者。
我认为这份特定的文档,尽管它是一份非常好的文档,并不支持原文中描述的设计文档流程。它看起来像是尽管有流程,而不是因为流程而做出的好工作。这显然只是一个数据点,但我会将其视为一个负面点。
我不知道是否有人对流程是否良好进行过正式调查?
我见过最接近的例子是Oxide计算机公司的RFD文档,其中许多是公开的。
示例:https://rfd.shared.oxide.computer/rfd/0177
主索引:https://rfd.shared.oxide.computer
这是一个很棒的格式,尤其是图表部分。我很高兴看到这些工具是公开的:https://github.com/oxidecomputer/rfd-site
公司将知识产权保密?有点奇怪……
我猜在开源领域,我们会讨论那些拥有最详尽README文件的GitHub项目……
我曾参与过一个为期六个月的项目,该项目有一份9页的设计文档,但负责的总监从未签字确认——然而工作必须启动。
项目按时(成功)交付,但项目经理在次日对设计文档提出了反馈,并要求调整方法。
尴尬的是,该项目经理完全不知晓项目已在前一天未经其审核的情况下交付,他随后专门与我召开会议,为数月来忽视审核和批准设计文档的请求一事致歉。
我讨厌设计文档。我甚至不在谷歌工作,但曾在采用设计文档文化的地方工作过。感谢谷歌。
我看不出来设计文档在你描述的情景中是问题所在
我并不反对。我没有提到的是,由于等待导演的签字批准,项目被推迟了数周。
在项目发布6个月后才收到过时的审批和修改请求,这让我更加确信设计文档只是毫无实际用途的技术废话。
谷歌员工在这条评论中的回复让我感到惊讶。我实际上发现设计文档对团队入职和在进行更改时进行异步利益相关者沟通非常有用。设计文档通常也会导致出色的g3doc文档。这比不得不从团队中搜集关于系统设计选择的零散知识要好得多。
设计文档很棒,但谷歌的写作文化高度碎片化且相当零散。我更偏好亚马逊的写作文化(尽管我讨厌亚马逊文化中的其他一切)。
亚马逊通过写作在会议中倾向于采取行动。他们的文化中有DRIs(或独裁者),他们有权做出决定,这种权力伴随着对所做决定的一定程度的问责。在亚马逊,文档会被阅读,各方讨论后做出决策。而在谷歌,文档很少被完整阅读,更多是评论,且在所有利益相关方就共同方向达成一致前不会做出决策。
亚马逊的方式毒性更小,但需要撰写者投入大量精力制作高质量文档。个人认为亚马逊的方式更好,但仅因其独特文化才行得通。
这与我在谷歌的经历不同。我们通常会同时开始工作并提交设计文档审核,可能只需等待一两天即可收到首批评论。
通常可以判断哪些部分不会引发争议,并从这些部分开始。
在我任职期间,这些通常被称为STO(最终决策者),而非DRI(直接责任人)。亚马逊的文档概念在单一负责人模式下很出色,然而亚马逊也面临文化和增长问题,随着团队和组织扩大,多个文档“负责人”的出现与贝索斯曾倡导的理念直接矛盾,导致新功能和产品设计沦为委员会决策。当然这取决于组织,但我认为这是贝索斯离任后公司成长过程中“第二日文化”渗透的结果。
这高度取决于团队和项目。项目越模糊,就越可能无法做出决策,你将不得不安排后续会议,并准备更多文档和更多参与者。
是的,委员会式设计将持续下去,直到士气好转。
亚马逊的员工流动率很高,不是吗?我好奇他们对文档的投入有多么关键,以确保公司正常运转——否则员工离职时会带走所有知识。但如果文档记录下来,就可以传承下去。
在该公司工作了6年,我从未见过一份最新的設計文档。最多只有一个高层次的示意图。
这些文档在实施开始时就已经过时了,具体程度因项目而异。
顺便说一句,我认为这个平均任职年限的数据很久没有更新了。例如在伦敦,三分之一的员工在这里工作了超过5年。
美国(大部分员工所在地区)的平均工龄仍接近2年,除非在短短几年内发生了重大变化(我曾是那里的高级开发经理,并在那里工作了大约6.5年)。这与其他大型科技公司的情况大致相同,微软除外。英国和欧洲整体而言是个不恰当的比较对象,因为那里选择较少且工作预期差异显著。
我觉得人们在这里可能会因小失大。谷歌的设计文档没什么特别之处。真正特别的部分是难以在其他地方复制的:这些文档经常收到有见地的评论和反馈,这些评论和反馈能避免大量时间和资源的浪费,而作者们会有选择性地采纳这些评论。这源于对专业知识的掌握和对工作的投入,而后者在近期整个行业中都显得匮乏,包括谷歌在内。
有人知道在哪里可以找到go/greendoc的副本吗?
它很有用,但据我所知,不同团队的设计文档结构各不相同。当我还是实习生时,我被go/greendoc吓到了,于是打开一个空文档,根据团队现有的设计文档开始撰写……结果效果更好。归根结底,这只是技术写作。
greendoc模板几乎没有内容,我不确定它在谷歌以外是否有价值。
我在谷歌工作过,但对此持不同意见
或许你指的是另一份文档,或者它已经发生了变化。我去查看了一下,它实际上只有两页,包含五个标题(都在这篇帖子中提到了)。
在我看来,还有一些更好的文档,以及一些关于写作和示例的出色内部文档。我希望这些能公开。
不,我认为就是这样。
为什么这么做?如果你觉得这个流程值得在其他地方复制,只需用自己的话重新撰写那几段说明即可。
我甚至已经不记得那些章节具体内容了
谷歌有一个名为“One-pager”的简版设计文档概念
2018年,这个“One-pager”的模板长达两页
“一个明确的信号表明文档可能不需要,就是那些实际上是实施手册的设计文档。”
在我工作的公司,这就是他们对设计文档的要求。他们希望它能够让任何人接手并实施。
HN对此有何看法?
而在产品层面,产品需求文档在推出新功能时始终有用,因为它整合了所有联系信息、文档、支持资料、沟通记录等。你总是希望在维护良好产品需求文档的产品中工作。
> 你总是希望在维护良好的产品上工作。
这确实很不错。但我从未见过让我感到满意的。我见过一些。
当大语言模型(LLMs)流行起来时,我曾希望找到一种比现在更轻松的方法来应对制定要求的问题。
对我来说,计算机编程是一种沟通形式,其中需求更接近人类,而程序代码更接近机器。在计算机一侧,我们有代码检查工具、编译器和一个确定性系统来执行代码。在人类一侧,我们有人提出需求,例如“系统应该易于使用”。
这是一个很好的习惯。我希望所有项目都有一个编码风格文档。在我看来,编码哲学比工具和语言选择重要得多。没有这样的风格指南,就像在建筑项目中雇佣建筑工人却不让他们看计划一样。
不过,关于这一点:
– 确保考虑横切关注点。
我的回答是“避免横切关注点,因为它们违反了关注点分离原则;一种横切类型的违反” ;p
我的观察是,虽然避免横切关注点初看起来可能有挑战性,但创建一个避免它们的代码架构会导致更易于维护和理解的代码。我参与过许多复杂项目,包括分布式系统、区块链、点对点消息系统等,但尚未遇到无法通过结构设计完全避免横切关注点的项目。
不过,我认为文章中提到的“安全、隐私、可观察性”等并非独立的“关注点”,而是软件组件的期望特性。
或许可以阅读专门讨论此点的章节:https://www.industrialempathy.com/posts/design-docs-at-googl…
一些横切关注点不仅涉及代码,还包括“如何监控系统的可靠性?”或“该系统读取用户敏感数据,如何对这些读取操作进行审计?”等问题。通常答案很简短:“使用标准系统xyz”——但确保这一方案得到落实同样重要。
有道理。定义可以很宽泛。术语“横切关注点”让我联想到面向切面软件开发,它有非常具体的定义,并且倾向于采用特定方法,如依赖注入。
例如,在面向方面开发中,他们倾向于将日志记录器注入到所有组件中;但其他开发方法可能选择让消息和错误沿组件树向上传播(例如,对于非错误消息,可能使用事件发射器、消息传递、回调或其他类型的通道)。但核心思想是,所有组件的消息应在应用程序顶层的中央位置进行聚合、处理和日志记录;因此无需将日志记录器实例注入每个组件,这可降低组件与应用程序其他部分的耦合度。此外,日志记录可能只是对这些消息进行处理的其中一种方式。
将此逻辑置于代码顶层附近非常有益。我认为当系统的重要输出(开发者或用户可直接观察的内容)可从单个源文件(或尽可能少的文件)追溯时,这极具价值。
创建与快速迭代
审查(可能分多轮进行)
实现与迭代
维护与学习
缺失的第5步:推广与废弃
设计文档是软件开发的“mise en place”。
(2020)
更多讨论:
https://news.ycombinator.com/item?id=23915521
说得对,尤其是在技能多样化的大型团队中。
真希望看到AMP的设计文档……
有没有实际的例子?
“设计文档”是否导致Gmail中的IMAP被淘汰?
我不太明白你的评论。你认为Gmail的IMAP发生了什么或正在发生什么?
不知道楼主怎么想,但情况是这样的:
https://workspaceupdates.googleblog.com/2023/09/winding-down…
这意味着基本上只有经过 Google 批准的 OAuth 应用才能在未来使用 IMAP。
有趣,感谢分享。我可能错过了这个信息。不传递主要谷歌密码似乎并不完全不公平,而且如果真的需要该功能(可能),你可能仍然可以使用生成的应用程序密码。
这里令人困惑的是,过去你需要启用“不安全应用”才能使用应用程序密码,而文章中提到这一功能将被移除,适用于个人账户。虽然他们没有明确表示要移除个人账户的IMAP应用密码功能,但存在实际效果上被移除的担忧。
有趣。我偶尔会使用这个功能,会继续关注。感谢澄清。
Gmail通过标签扭曲了IMAP,因此使用“他们的”IMAP服务的唯一正确方式是通过“他们的”IMAP客户端,这与标准的初衷相悖。我以为这是常识,因此在最初的评论中没有详细说明。
请记住,谷歌保留复制数据库的权利,因为这些数据库未受版权保护。