Definition 定义
A design document is a technical report that outlines the implementation strategy of a system in the context of trade-offs and constraints.
设计文档是一份技术报告，概述了系统在权衡和约束背景下的实施策略。
Goal 目标
Think of a design document like a proof in mathematics. The goal of a proof is to convince the reader that the theorem is true. The goal of a design document is to convince the reader the design is optimal given the situation.
将设计文档想象成数学中的证明。证明的目标是让读者相信定理是正确的。设计文档的目标是让读者相信设计在当时的情况下是最佳的。
The most important person to convince is the author. The act of writing a design document helps to add rigor to what are otherwise vague intuitions. Writing reveals how sloppy your thinking was (and later, code will show how sloppy your writing was).
最需要说服的人是_作者_ 。编写设计文档的行为有助于增加原本模糊的直觉的严谨性。写作揭示了你的思维是多么草率（稍后，代码将显示你的写作有多草率）。
Organization 组织
Good design document organization is as important as code organization. You probably have opinions about code organization. You’ve probably used the phrase “spaghetti code” to describe poorly-organized code. Most programmers write “spaghetti design docs” unless they’ve had a lot of practice.
良好的设计文档组织与代码组织同样重要。您可能对代码组织有意见。您可能已经使用过“意大利面条代码”这个短语来描述组织不善的代码。大多数程序员都会编写“意大利面条设计文档”，除非他们有过大量练习。
Let me illustrate a common code organization issue some programmers run into on their first day. The novice writes
让我来说明一些程序员在第一天遇到的一个常见代码组织问题。新手写道
terminal.print("Hello world")Then they decide they want to make the text red, so they edit their program to
然后他们决定要将文本设为红色，因此他们将程序编辑为
terminal.print("Hello world")
terminal.setPrintColor("red")And then they’re confused that it didn’t come out red. They haven’t internalized that the first line of code happens before the second. They just get a soup of code on the screen that kind of has the ingredients for a program, and expect the computer to do what they want.
然后他们很困惑，因为它没有变成红色。他们还没有内化第一行代码发生在第二行_代码之前_ 。他们只是在屏幕上看到一堆代码，这些代码具有程序的成分，并期望计算机做他们想做的事。
Novice document writers make the exact same mistake, but with prose instead of code. They get a soup of sentences and paragraphs and expect the reader’s brain to do what they want.
新手文档编写者会犯_完全_相同的错误，但使用散文而不是代码。他们得到一堆句子和段落，并期望读者的大脑做他们想做的事。
If the reader is smart enough, you might actually get away with this. Just like an expert programmer can mentally untangle spaghetti code.
如果读者足够聪明，你实际上可能会逃脱惩罚。就像专业程序员可以在脑海中解开意大利面条代码一样。
But a perfect doc is written such that the reader is never surprised. The reader should find that every sentence flows obviously from the previous ones. They should finish your doc and think “well this was entirely straightforward, why did we even need to have this meeting?“.
但是，写出完美的文档，让读者_永远不会感到惊讶_ 。读者应该会发现，每句话都明显来自前面的句子。他们应该完成你的文档并想“好吧，这完全简单，我们为什么还需要开这个会议？
This disappoints the ego-seeking behavior of many engineers. Good engineers often want people to realize how clever they were.
这让许多工程师的自我追求行为感到失望。优秀的工程师通常希望人们意识到他们有多聪明。
But a good doc will lay out the problem and mental models in a way that the solution that took weeks of hard thought to invent will be clear to the reader by the time the doc presents it.
但是，一个好的文档会以一种方式列出问题和心智模型，当文档呈现时，读者会清楚地看到需要数周的艰苦思考才能发明的解决方案。
This also requires having a good model of the minds of the people reading your doc. The goal of your doc is to take their minds from their current state to a new state in which they believe your design is a good one.
这也需要有一个很好的模型来了解阅读您的文档的人的想法。你的文档的目标是让他们的思想从他们当前的状态进入一个新的状态，在这种状态下，他们认为你的设计是一个好的设计。
You should anticipate every objection someone would have and preemptively show why it’s invalid, so that the reader never even thinks to bring it up.
你应该预见到某人会提出的每一个反对意见，并先发制人地说明为什么它是无效的，这样读者甚至永远不会想过提出它。
Many engineers fail at modeling the starting state of their readers’ minds, so fail at getting them to the destination state.
许多工程师未能对读者思维的起始状态进行建模，因此无法让他们达到目标状态。
Editing 编辑
Once you’ve got the information organized and laid out properly, the next step is to edit for length. Remove every word that can be removed. Do this because your readers’ attention is a scarce resource.
正确组织和布局信息后，下一步就是编辑长度。删除所有可以删除的单词。这样做是因为读者的注意力是一种稀缺资源。
Unless you’re an unusually terse writer, you can almost always cut length by ~30% from the first draft without sacrificing information.
除非你是一个异常简洁的作家，否则你几乎总是可以在不牺牲信息的情况下从初稿中减少 ~30% 的长度。
The easiest way to get good at editing by going through other people’s docs with a red pen and crossing out unnecessary words. You’ll find tons. It’s easier to criticize other people.
擅长编辑的最简单方法是用红笔浏览_其他人_的文档并划掉不必要的单词。你会发现很多。批评别人更容易。
Once you’ve built this muscle, you can turn the weapon on yourself. Distilling thoughts to fit into the 280 character tweet limit is also surprisingly good practice.
一旦你锻炼了这块肌肉，你就可以把武器转向自己。提炼想法以适应 280 个字符的推文限制也是令人惊讶的好做法。
Volume 卷
There’s no substitute for lots of practice. I’m grateful for having worked at AWS with a unique doc-writing culture. The first docs I wrote there were terrible, but after a few hundred, I like to think they were pretty good.
大量的练习是无可替代的。我很感激能在 AWS 工作，拥有独特的文档写作文化。我在那里写的第一批文档很糟糕，但在几百个之后，我喜欢认为它们相当不错。
For unfamiliar readers: Amazon meetings start with the presenter passing out copies (historically physical, though increasingly digital since Covid) of a prose document. The document is 1-6 pages depending on the importance.
对于不熟悉的读者：亚马逊会议从演示者分发散文文档的副本（历史上是实体的，尽管自 Covid 以来越来越数字化）开始。该文件根据重要性为 1-6 页。
The meeting starts with everyone sitting in silence, reading the document, and adding notes and questions in the margins with red pen. Watching people mark up the document you spent so much time polishing is a strong forcing function to become a better writer.
会议开始时，每个人都静静地坐着，阅读文档，并用红笔在空白处添加注释和问题。看着人们标记你花了很多时间润色的文档是成为一名更好的作家的_强大_强迫功能。
Concrete tips 具体提示
These work for me, but they may not work for you.
这些对我有用，但对你可能不起作用。
Use short paragraphs 使用短段落
You should think of your doc as a series of bullet points that flow into each other. That is, a doc might be organized like:
您应该将文档视为一系列相互流入的要点。也就是说，文档的组织方式可能如下：
- Observation A 观察 A
- Observation B 观察 B
- Because B, idea C
因为 B，想法 C - But problems D and E
但问题 D 和 E - Observation F 观察 F
- Therefore idea G 因此，想法 G
- And improvement H 和改进 H
Each of those bullets should be a paragraph that can be summarized in a single sentence. It doesn’t need to be a single sentence — you can elaborate where necessary. But, once read, the reader should be able to compress it to a single sentence in their mind.
这些项目符号中的每一个都应该是一个可以用一句话概括的段落。它不需要是一句话——您可以在必要时详细说明。但是，一旦阅读，读者应该能够在脑海中将其压缩为一个句子。
This is related to the idea of editing, and that your reader’s attention is a scarce resource. Your reader has a finite amount of stuff they can juggle in short-term memory. Writing in this “one idea per paragraph” style allows the reader to compress the paragraph and thus consume less of this scarce resource.
这与编辑的想法有关，读者的注意力是一种稀缺资源。您的读者可以在短期记忆中处理的东西数量有限。以这种“每段一个想法”的风格写作可以让读者压缩段落，从而减少这种稀缺资源的消耗。
Use an appendix 使用附录
If there is some number in the doc that is the result of a complex calculation or simulation, don’t include that in the body of the doc. Use a footnote like:
如果文档中有一些数字是复杂计算或模拟的结果，请不要将其包含在文档正文中。使用脚注，例如：
A monte-carlo simulation[1] showed the probability of data loss due to corruption is less than 1 in 10^12
蒙特卡洛模拟[1]显示，由于损坏而导致数据丢失的概率小于10^12分之一
Then describe the simulation in more detail in the appendix. The appendix should not be necessary to read to understand the main conclusion of the doc. It’s only there for the curious reader to check your work if they want.
然后在附录中更详细地描述模拟。无需阅读附录即可理解文档的主要结论。它只供好奇的读者根据需要检查您的作品。
Worked editing example 工作编辑示例
Here’s a paragraph from above before I edited it:
这是我编辑之前上面的一段话：
Each one of those bullet points should be its own paragraph in your doc. And each paragraph should be summarizable in a single sentence. The paragraph doesn’t need to actually be a single sentence. For example, you might include a few more sentences to really illustrate the whole concept you’re trying to convey. But, once the reader has read it, they should be able to compress it to a single sentence in their mind.
这些要点中的每一个都应该是文档中自己的段落。每个段落都应该可以用一句话来总结。该_段落实际上不需要_是一句话。例如，您可以添加更多句子来真正说明您想要传达的整个概念。但是，一旦读者读完它，他们应该能够在脑海中将其压缩为一个句子。
And here is the edited version that conveys the exact same information, but smaller:
这是传达完全相同的信息的编辑版本，但更小：
Each of those bullets should be a paragraph that can be summarized in a single sentence. It doesn’t need to be a single sentence — you can elaborate where necessary. But, once read, the reader should be able to compress it to a single sentence in their mind.
这些项目符号中的每一个都应该是一个可以用一句话概括的段落。它不需要是一句话——您可以在必要时详细说明。但是，一旦阅读，读者应该能够在脑海中将其压缩为一个句子。