什么是记录软件项目的好方法和坏方法？

Question

我负责找到一个很好的方式来记录我正在处理的软件项目。

什么事情对文档很重要？代码和设计的文档主要以评论的形式出现在代码中？我们是否应该直接在源代码控制中使用代码来创建文本文件或Word文档？我们应该使用wiki吗？

需要考虑的因素包括当前团队创建文档的容易程度，以及其他开发人员稍后如何查找，更正和扩展文档。我从很多项目中获得的经验是，开发人员往往不写文档，因为编写系统太复杂或者开发人员不友好，而且几年后，新开发人员很难找到所写的小文档。

我对您在类似项目中使用的方法感兴趣。什么运作良好，哪些运作不好，为什么？

关于该项目的一些关键事实：

• 该平台是C＃和.NET。
• 我们使用Visual Studio和Team Foundation Server进行源代码管理和工作项目（任务）管理。
• 我们使用Scrum和测试驱动开发，并受到领域驱动设计的启发。
• 该软件由一组Web服务和两个GUI客户端组成。
• 其他客户将在未来与Web服务集成。整合将由其他团队的其他开发人员完成（所以Web服务构成一种API）。
• SharePoint在整个开发环境中广泛使用。大多数项目都有一个SharePoint网站，包括我们的。
• 在我们项目的SharePoint网站上，我们目前有大量MS Office文档，包括需求，设计，利益相关方演示文稿等。保持所有内容都是最新的。
• 我们还为开发团队开发了一个SharePoint wiki，我们在这里以非结构化的方式记录事物。例子包括我们的构建脚本是如何组织的，我们的测试策略，编码指南。
• 该软件是一个相当大的金融机构的内部应用程序。
• 该软件由6人组成的团队在大约1年的时间内开发而成。
• 开发人员只是为这个项目聘请的顾问，并且将来无法提供帮助（除非客户决定为此付费）。
• 客户对如何记录此类项目几乎没有指导。

Answer 1

首先也是最重要的一点，就是用NDoc可以解析它们的方式写下评论。这是让代码本身记录下来的最好方法，因为开发人员必须非常少地更改其开发实践，并且可以生成解释代码的页面，而无需查看代码。

其次，让开发人员编写文档并不容易，而让他们这样做可能是徒劳无益的。这是Fogbugz等产品发挥作用的地方。他们将帮助用门票来管理开发，帮助跟踪支票登记，并在完成迭代时生成发行说明。

总之，您最好的选择是找到适合开发者现有流程的最有效的解决方案。如果它很少影响他们的发展过程，他们将更有可能采用该系统。

Answer 2

G'day，

绝对使用维基。我推荐TWiki，因为它是一个优秀和广泛的维基实现，不需要太复杂的安装和管理。

这里有一些初步想法。

分类：

开始了与你想要营造的初始本体，但

• 让人们根据需要添加新的类别或子类别，
• 让人们根据需要修改（子）类别，也许按照此协议达成协议，所以对于基本上相同的东西，您不会得到多个名称的碎片。
• 让任何初始（子）类别如果留空，就会枯萎并死亡。在项目结束时执行此操作，因为有些区域可能只有项目结束时才会有条目。

标记：

开始使用标签云。顺便提一下，这是TWiki的一个很好的插件，可以在项目的早期阶段开始分类内容。改造标签几乎是不可能的。提前开始标记也可以让人们搜索可能已经存在的信息，而不是在多个地方找到相同的信息。

HTH我会回来，并添加更多的点，因为我认为他们。

Answer 3

对我来说最糟糕的是比缺少文档是多余的的文档。

请记住，是的：记录您的项目非常重要，而且您的文档的主要部分始终有风险永远不会被读取。

因此，我认为一个好的出发点在于考虑您的文档更像是您可能用于向您的项目介绍新开发人员的内容，而不是您对软件内部工作的详细描述。

Answer 4

我认为要记录的最重要的事情是决定。这适用于从需求到架构选择的所有内容。模块X的要求是什么？这些要求在体系结构中如何表示？你为什么选择建筑模式A而不是B？有什么好处？源代码也是如此：众所周知，评论为什么比要好得多。

无论您使用Wiki还是使用Word制作的需求文档，您如何记录这些决定无关紧要。更重要的是这些文件始终是最新的，任何人都可以轻松访问它们。正如你所说，这可以通过使用wiki或将文档放在源代码控制之下来实现。如果只有少数人可以访问他们，他们更有可能不会更新，不必在必要时阅读。

我们对当前的项目使用维基，它工作得很好。任何人（开发人员，管理人员和客户）都可以轻松访问，并且历史可以跟踪更改，因此您知道发生了什么变化以及原因。此外，我们试图以一种有意义的方式记录代码并记录主要的设计决策。我们尽量不要记录太多，例如小事情，因为总是很难保持这些东西是最新的，这是不值得的努力，恕我直言。