编程与软件工程industrialempathy.com编辑精选
Google 的设计文档实践
Design Docs at Google
2020 — 2024，它一次次回到首页
黑点是上首页（≥ 50 分）的那次投稿，空心点是没冲上去的投稿，点越大分数越高。
导读
这篇文章系统介绍了 Google 内部的设计文档（design doc）实践：在动手写代码之前，先用一份文档阐述问题、设计思路、替代方案和权衡，并通过评审批次在相关团队间达成共识。作者把设计文档比作软件工程的蓝图，认为它是 Google 工程文化的重要组成部分。
为什么经久不衰：设计文档是跨团队协作和大型项目绕不开的实践，这篇文章来自 Google 的一手经验，具体可操作，因此每隔几年都会被重新翻出来讨论。
HN 评论精选
设计文档是写代码前的蓝图，用于跨团队达成共识，评审反馈也与代码评审不同。
设计文档是我在软件工程里最喜欢的东西之一。如果说代码是砖瓦，那这些文档就是蓝图。我知道这有点争议，但我们的工作不只是写代码——在组织里穿行、在多个团队和技术之间达成共识，占了很大一部分。设计文档就是在写下几千行代码之前把这些事情理清楚的方式。而且文档评审给出的反馈，和代码评审给出的反馈也截然不同。
cameronbrown查看英文原文
Design docs are one of my favourite things about software engineering. If code is the bricks and mortar, then these docs are the blueprints. I know this is fairly controversial, but our jobs isn't just to write code. Navigating organisations and achieving consensus between a lot of teams/technologies is a huge part of it. Design docs are a way to get all of that out of the way _before_ writing thousands of lines of code. The review process nets significantly different feedback to code reviews too.
Google 内部写设计文档用的 Google Docs 并不适合技术文档，工具本身也没有改进。
我在 Google 工作了四年。一直让我惊讶的是，Google 的文档用的就是 Google Docs（和大家一样），却似乎从没兴趣把它变得没那么难用。它过度面向打印（如今谁还打印 Google 文档？），对预格式化文本（比如代码）毫无支持，基本不支持数学公式。事实上，自诞生以来它反而变得更不适合技术文档了——早期版本至少还允许自定义段落样式。我原以为 Google Colab 会演变成一个更好的通用技术规格写作工具，但它似乎并没有往那个方向走。
staplung查看英文原文
I worked at Google for 4 years. One thing that has always surprised me about documentation at Google is that they use Google Docs (just like everyone else) but have never seemed interested in making it less of a terrible tool for the task. It's relentlessly print oriented, which makes almost no sense these days (when was the last time you printed out a Google doc?), has no affordances for dealing with pre-formatted text (e.g. code), has basically no support for mathematical formulas, etc. In fact its actually evolved to be less suited to the task of technical documentation since it began given that earlier versions at least allowed you to define your own paragraph styles. I was hoping that Google Colab might evolve into a better/more general tool for writing tech specs but it doesn't seem to be moving in that direction really.
过度正式的文档会扼杀敏捷；靠经验丰富的团队和「部落知识」反而能高效开发，但这需要好的管理和人才留存。
我倾向于尽可能减少文档，或者保持尽可能模糊。因为我来自一个坚持极其详尽、正式、所有人都要签字（连洗手间服务员都要）的文档的环境。这些文档变成了「混凝土套鞋」，把本该敏捷迭代的项目变成了瀑布流巨兽：花了大钱，拖了很久，交付的东西没人想要。我怀疑我现在的做法在很多组织行不通，因为它基本上要求所有参与者都极其有经验，并且作为团队长期待在一起。我逐渐意识到，「部落知识」并不是人们想象中的怪物，而是实现高质量、快速、自适应开发的一种方式。主要问题在于它确实需要好的、有同理心的管理，需要长期留住有经验、有能力的人，以及「学徒」模式。这些在当今企业界（至少在美国）并不流行。
ChrisMarshallNY查看英文原文
I'm of a mind to reduce documentation as much as possible, or keep it as vague as possible. That's because I came from an environment that insisted on incredibly detailed, formal, approved-by-everyone-including-the-mens-room-attendant, documents. These became "concrete galoshes"[0] that turned what should have been an agile, iterative project into a waterfall behemoth that cost a mint, took forever to make, and delivered a result that no one wanted. I suspect that my current process[1] would not be acceptable for many organizations, as it basically requires that everyone involved be extremely experienced, and kept together as a team for years. I've actually come to realize that "tribal knowledge" is not the boogeyman that its made out to be; but is a way to get very high-quality, rapid, adaptive, development done. The main issue is that it does require good, empathetic management, long-term retention of experienced, capable people, and an "apprenticeship" model. These are not popular concepts in today's corporate world (at least, in the US). [0] https://medium.com/chrismarshallny/concrete-galoshes-a5798a55af2a [1] https://medium.com/chrismarshallny/forensic-design-documentation-54541925d30e
老设计文档是理解公司技术史的珍贵材料；开源项目普遍缺乏这类文档，尤其是记录被否决方案的文档。
如果你在 Google 工作，有个好玩的事是去读古老的设计文档，比如 Bigtable 的原始提案。它们大多相当简短，而且是传奇人物写的。这些文档就像公司的《联邦党人文集》，能让你真正理解公司是怎么走到今天的。我特别喜欢读那些刺眼的部分——描述的东西显然没进最终实现，或者后来被删掉了。想想当时他们为什么觉得这些值得写下来，很有意思。写到这里我觉得有点可惜：开源软件很少有设计文档，即使有些项目源自设计文档文化很好的公司。哪里能找到一份文档，讨论 Kubernetes 或 gRPC 考虑过又否决了哪些替代方案呢？
jeffbee查看英文原文
A fun activity if you’re a Googler is to go read ancient design docs, like the original pitch for bigtable. They are pretty short for the most part, and they were written by the legends. These are the Federalist Papers of your company, they give real context to how the company arrived here. In particular I always enjoyed reading the jarring parts were they describe something that definitely did not make it into the implementation, or got removed later. It’s interesting to think about why they considered those things important enough to write down at the time. Now that I wrote the above, it's a bit sad that there aren't many design docs for open source software, even ones that originated from companies with good design doc culture. Where's a doc that discusses alternatives considered and rejected for kubernetes or grpc?
历次讨论
同类还值得读
开源应用架构
The Architecture of Open Source Applications
《开源软件架构》（AOSA）是一本在线免费书，邀请知名开源项目的作者亲自剖析其内部设计，涵盖 SQLAlchemy、LLVM、Audacity、Apache、Bash 等系统。
编程与软件工程上首页 9 次 · 2011–2024aosabook.org编辑精选编程语言简史：简短、不完整且多半错误
A Brief, Incomplete, and Mostly Wrong History of Programming Languages
一篇以戏谑、故意不准确的方式回顾编程语言史的博客文章，用夸张轶事和讽刺定义串起 Lisp、C、C++、Java、JavaScript、PHP 等语言。
编程与软件工程上首页 8 次 · 2009–2021james-iry.blogspot.comSQLite 是如何测试的
How SQLite is tested
SQLite 官方文档页，系统介绍 SQLite 的测试体系：多种测试方法（TCL 测试、模糊测试、回归测试、静态分析等）和海量测试用例，展示了这个小型开源项目如何靠极致测试获得…
编程与软件工程上首页 8 次 · 2009–2025sqlite.org编辑精选高级编程语言（2009）
Advanced programming languages (2009)
Matt Might 的经典文章，按用途推荐“高级编程语言”：如果追求就业就选主流语言，如果追求表达力、学术研究或创业，则推荐 Haskell、OCaml、Scala 等函数式语…
编程与软件工程上首页 8 次 · 2009–2022matt.might.net我的 Forth 与栈机器经历
Yosefk - My history with Forth & stack machines
作者以亲身经历回顾了使用 Forth 语言和栈式机器的历程：既赞叹其简洁优雅、代码量小、可自举的优点，也坦率指出栈操作在实际编程中的痛苦，以及 Forth 社区文化中的问题。
编程与软件工程上首页 8 次 · 2010–2024yosefk.com编辑精选