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.你可能不是唯一对某项设计决定感到疑惑的人，所以你的问题也会帮助其他人成长