为项目文档分配资源

Question

您对以下情况有何建议：

许多开发人员需要构建和设计复杂的系统。需要为未来的开发人员记录此设计，并且必须注意设计决策。这些报告大约每两个月进行一次。我的问题是如何记录这个项目。

我看到两种可能性。每个开发人员都会写下他们帮助设计和集成的内容，然后一个人将每个文档组合在一起。由于负责组装所有部件的人没有太多时间来调整每个部件，因此有时候最终文件可能会不连贯或多余。

假设每个开发人员的文档部分在截止日期前几天到达。协作系统（即wiki）无法正常工作，因为直到截止日期前几天才能阅读。

或者，在团队的其他成员真正开发系统的过程中，是否有少数人（2-3）负责编写文档？开发人员需要一种方法将他们的设计选择和结论转移给技术作家。怎么能有效地完成？

Answer 1

我们使用汇合（atlassian的wiki-like-thing）并记录各种不同的“事物”。开发人员不断地做到这一点，我们互相推动文档 - 我们让同伴的压力决定了什么是必要的。每当有新人出现时，他/她的任务是阅读所有内容并找出仍然是正确的。由于此原因，删除或更新了不正确的内容。我们很高兴能够删除内容;）

这个过程的好处是相关的东西保持不变，不相关的东西被删除。我们总是从更正式的要求中“逃脱”，声称如果“他们”需要它们，我们总能构建他们想要的文件。 “他们”从不需要他们。

Answer 2

我认为备选方案2的灵活性较低，因为它意味着项目的新阶段（尽管它可能与测试并行）。

如果您处于敏捷模型中，那么只需添加文档（遵循指南）作为故事 如果您采用分阶段方法，那么我仍然会要求开发人员按照一些指导原则处理文档，并在设计和代码中查看文档。最后，你可能会有一位技术作家审查一切正确的英语，但这将是一种“释放”活动。

Answer 3

我们使用RUP风格方法从两个方面接近这个。在第一种情况下，您将拥有一名领域专家，负责粗略设计您将要提供的内容 - 开发人员可以根据需要进行切换。在第二种情况下，我们使用技术作者 - 他们记录应用程序，因此他们应该很好地了解它是如何挂在一起的，并且您通过设计和开发过程直接参与其中。在这种情况下，它们可以帮助改进设计，并确保它与他们认为正在开发的设计相匹配。

Answer 4

我认为您可以使用Sand Castle来记录您的项目。

检查出来

Sand Castle from Microsoft

Answer 5

这不是一个完整的文档，但确保使用Doxygen-style comments注释接口等意味着编写代码并将其记录在一起更近。

这样，开发人员应该记录他们的工作。我仍然认为需要建筑师进行审查以确保一致的质量，但确保人们记录他们所做的工作是确保他们遵循架构的最佳方式。