如何才能写出好的软件设计文档？软件设计文档模板( 二 ) _软件

我倾向于将这一部分视为项目任务跟踪器，因此每当范围估计发生变化时，我都会更新它。但更像是个人喜好。
怎样才能写好文档？
谈完了一份优秀的设计文档应该包含哪些内容，现在来谈谈写作风格。
尽可能保持简单。
不要把设计文档写成你读过的学术论文。论文旨在打动期刊评论家，而设计文档旨在描述你的解决方案并获得他人的反馈。您可以通过以下方式使文档更加清晰:
简单的词
使用短句
使用符号列表和编号列表。
提供具体例子。
添加图表
图表很容易比较几个选项，通常比文本更容易理解。我经常使用Google Drawing来创建图表。
请记得在截图底部添加图表源文件的链接，以便在发生变化时更新图表。
包括数字
问题的规模通常决定了解决方案的规模。为了帮助审阅者更好地了解情况，请在文档中使用实际数字，如数据库行数、用户错误数、延迟以及这些数据和使用情况之间的关系。(还记得大O记号吗？)
添加利息
记住，技术规范不是学术论文。另外，人喜欢看有趣的东西，但不要为了好玩而偏离核心思想。
自我检查
在将设计文档发送给他人审阅之前，假装是审阅者。你对这份设计文件有什么问题吗？然后在发出文档之前解决这些问题。
假期测试
如果你是独占性的，无法访问，团队中的其他人是否可以阅读这个文档，并按照你的意图实现文档的内容？
设计文档的主要目的不是为了分享知识，但这是评估清晰度的好，这样别人可以给你提供有用的反馈。
流动
设计文档可以帮助你在浪费大量时间去实现错误的解决方案或者解决错误的问题之前得到反馈。获得好的反馈是一门艺术，但那是另一回事了。现在，让我们讨论如何获得设计文档的反馈。
首先，参与项目的每个人都应该参与设计过程。即使很多决策是技术总监做的，也没关系。至少每个人都应该参与讨论并收到他们的设计。
其次，设计过程不一定是盯着白板，在上面画各种创意。您可以手动设置各种可能的解决方案的原型。这不同于在编写设计文档之前编写代码。你可以写一些一次性代码来验证你的想法。为了确保您的代码仅用于概念验证，原型代码不能合并到主代码中。
在你知道如何执行项目后，请执行以下步骤:
请团队中有经验的工程师或技术负责人审阅您的文档。理想情况下，评估者应该是一个受人尊敬的人，他已经熟悉问题的边缘情况。
在有白板的会议室中复习。
向评审人员描述你正在解决的问题(这是非常重要的一步，不要跳过！) 。
然后向评委解释你想如何实现你的想法，让他们相信这是正确的解决方案。
在正式撰写设计文档之前完成所有这些步骤，可以帮助您在投入更多时间和最终确定解决方案之前尽快获得反馈。通常情况下，即使实现可以保持不变，评审人员仍然会指出一些需要你覆盖的极端情况，或者提及潜在的歧义，预测你未来可能遇到的困难。
然后，在你写好设计文档的初稿后，请之前的评审人员再读一遍，并在设计文档的“标题和人”部分写下他们的名字，作为对评审人员的鼓励，也意味着他们要对自己的评审行为负责。
添加审核人姓名时，考虑针对具体问题添加不同的审核人(如SRE和安全工程师) 。
审核后，请将设计文档发送给您的团队，以获得更多反馈。我建议把这个时间限制在一周左右，以免耽误。尽量在一周内解决他们遗留的问题。
最后，如果您和审阅者以及阅读本文档的其他工程师之间存在争议，我强烈建议您将这些争议放在文档的“讨论”部分。然后，与各方召开会议，讨论这些差异。
如果一个话题有5条以上的评论，面对面的讨论往往效率更高。记住，即使大家不能达成共识，你仍然可以做出决定。
最近和Shrey Banga聊到这个事情，了解到Quip也有类似的流程，只不过除了让团队中有经验的工程师或者技术负责人作为审核人之外，他们还建议不同团队的工程师来审核设计文档。我以前没有尝试过这种，但可以肯定的是，这有助于从不同观点的人那里获得反馈，从而进一步提高文档的质量。
以上步骤全部完成后，下一步就是开始实施了！在实现设计的过程中，设计文档可视为活动文档。在对实施计划进行调整时，同时更新文档，这样您就不必向所有利益相关者重复解释这些更改。

如何才能写出好的软件设计文档？ 软件设计文档模板( 二 )

如何才能写出好的软件设计文档？软件设计文档模板( 二 )