读程序员的README笔记14_技术设计流程（下）

1. 撰写设计文档

1.1. 设计文档以一种可扩展的方式来清楚地传达你的想法

1.2. 写作的过程会使你的思维结构化，并凸显出薄弱的环节

1.3. 把注意力集中在最重要的变更上，牢记目标和受众，练习写作，并保证你的文档是最新的

1.4. 文档持续变更

1.4.1. 并非每一项变更都需要设计文档

1.4.2. 3个标准来决定是否需要设计文档

1.4.2.1. 该项目将需要至少一个月的工程时间

1.4.2.2. 变更将对软件的扩展和维护产生长期的影响

1.4.2.3. 变更将显著影响其他团队

1.5. 了解撰写文档的目的

1.5.1. 设计文档是告诉别人某个软件组件是如何工作的

1.5.2. 设计文档的用途超越了简单的文档

1.5.2.1. 设计文档是一种工具，可以帮助你思考、获得反馈、让你的团队了解情况、培养新的工程师，并推动项目规划

1.5.3. 即使是在反馈很少的情况下，分发设计文档也能让团队了解情况

1.5.4. 传播设计知识将帮助其他人保持对系统的工作方式拥有准确的心理认知

1.5.5. 设计文档对于刚加入团队的工程师来说特别有帮助

1.5.5.1. 阅读大量的设计文档则要有效得多

1.5.6. 管理者和技术负责人使用设计文档进行项目规划

1.5.7. 如果一个项目是跨职能的，有了具体的设计文档，就更容易与其他团队协调

1.6. 学会写作

1.6.1. 写作拥有一种暴露你不知道的东西的能力

1.6.1.1. 编外：在这一点上我深有感触，非常同意

1.6.2. 写作作为一项技能，是通过实践来进步的

1.6.3. 写得清晰会让你的生活更轻松

1.6.4. 写作是一种有损的信息传递方式

1.6.4.1. 你把你的想法写下来，而你的队友则在他们的头脑中不完全地重建你的想法

1.6.4.2. 好的写作可以提高这种传递的还原度

1.6.4.3. 好的写作能力会为职业生涯添砖加瓦

1.6.4.4. 一份写得好的文档很容易被传阅给大团体，包括高管，而优秀的写作者不会被忽视

1.6.4.5. 你是否理解并不重要，重要的是他们是否能理解

1.6.5. 文档要简明扼要

1.6.5.1. 为了帮助你获得读者的视角，你需要去阅读别人写的东西

1.6.5.2. 想一想你会如何编辑他们的文章：哪些是多余的，哪些还需要补充

1.6.6. 不以母语为交流语言的开发者有时会对书面交流感到畏惧

1.6.6.1. 不要让语言障碍使你对撰写设计文档望而却步，不要担心语法是否完美，重要的是清楚地表达你的想法

1.7. 保证文档是最新的

1.7.1. 在从提案到文档的过渡过程中，有两个常见的陷阱

1.7.1.1. 第一个陷阱是提案文件被废弃了，再也没有更新

1.7.1.1.1. 实施过程中出现了分歧，而文档会对未来的用户产生误导

1.7.1.2. 第二个陷阱是，文档虽然被更新了，但提案的历史记录却丢失了

1.7.1.2.1. 未来的开发者无法看到那些导致设计决策的讨论，可能会重蹈覆辙

1.7.2. 务必保证你的文档是最新的

1.7.2.1. 如果你的设计提案和设计文档是两个独立的东西（比如Python PEP[插图]和Python文档），你需要使文档与已实现的方案保持同步，确保有其他人在你进行代码评审之后同步更新文档

1.7.3. 你需要对你的设计文档进行版本控制

1.7.3.1. 一个优秀的技巧是将设计文档与代码放在同一个库中进行版本控制

1.7.3.2. 代码评审也可以作为设计内容的评审意见，这些文档也可以随着代码的发展而更新

1.7.3.3. 请保留文档的整个历史记录，也包括讨论的内容

2. 协作设计

2.1. 与你的团队进行建设性的合作将产生更好的设计，但合作并不总是容易的

2.2. 理解你的团队的设计评审流程

2.2.1. 设计评审通知架构师即将发生的大型变化，并给潜在的使用者一个提供反馈的机会

2.2.2. 架构评审委员会和“请求裁定”(request for decision)是两种比较常见的方式

2.2.3. 不要等到最后的批准才开始写代码，要花时间实现原型和概念验证的“尖峰”，以增加对设计的信心，并给你一条更短的生产路径

2.3. 不要让人惊讶

2.3.1. 你需要有礼貌地并且渐进地让人们了解你的设计方案

2.3.2. 反馈会议不需要是正式的，也不需要专门来安排

2.4. 用设计讨论来进行头脑风暴

2.4.1. 头脑风暴会议的规模从2人到5人不等

2.4.2. 当一个问题特别多元或有争议时，要选择更大、更有包容性的头脑风暴会议

2.4.3. 设计讨论会议需要安排大块的时间，一般为两个小时左右

2.4.3.1. 思想需要时间来发展，尽量不要缩短讨论时间，让人们没有想法，或者只能疲于应付

2.4.4. 可能需要多于一次的头脑风暴会议来得出结论

2.4.5. 不要强加太多的条条框框在会议本身，思想需要“跳来跳去”才能探索想法

2.4.6. 在头脑风暴会议期间，做笔记可能会分散注意力

2.4.6.1. 白板也是一个“记录员”，你可以在讨论过程中拍照

2.4.6.2. 如果使用虚拟板，则可以保存中间的状态

2.5. 为设计出力

2.5.1. 你应该为你团队的设计工作贡献力量，而不仅仅是你自己的

2.5.2. 运用我们为代码评审提供的相同的指导，对设计进行全面的思考，考虑到安全性、可维护性、性能、规模等，要特别注意设计是如何影响你的专业领域的

2.5.3. 沟通要清晰，要尊重他人

2.5.4. 提出问题和给予建议一样重要，问题会帮助你成长

2.5.4.1. 你可能不是唯一对某项设计决定感到疑惑的人，所以你的问题也会帮助其他人成长