锐客网

  1. 首页 > 睿知 > >

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

生活知识睿知


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

推荐阅读


上一篇：如何辨别野生黑枸杞的真假

下一篇：四大教哪四个 四大教主