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

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改进这个问题？更新问题，以便 editing this post 可以用事实和引用来回答它.

8年前关闭。




Improve this question




我负责找到一种记录我正在从事的软件项目的好方法。

记录哪些内容很重要？代码和设计的文档是否应该主要以注释的形式出现在代码中？我们应该将文本文件或 Word 文档与代码一起直接放在源代码管理中吗？我们应该使用维基吗？

需要考虑的因素包括当前团队创建文档的难易程度，以及其他开发人员以后查找、更正和扩展文档的难易程度。我从许多项目中的经验是，开发人员倾向于不编写文档，因为编写它的系统太复杂或对开发人员不友好，而且几年后，新开发人员几乎找不到编写的少量文档。

我对您在类似项目中使用的方法感兴趣。什么效果好，什么效果不好，为什么？

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

该平台是 C# 和 .NET。

我们使用 Visual Studio 和 Team Foundation Server 进行源代码控制和工作项(任务)管理。

我们使用 Scrum 和测试驱动开发，并受到领域驱动设计的启发。

该软件由一组 Web 服务和两个 GUI 客户端组成。

其他客户端将在 future 与 Web 服务集成。集成将由其他团队的其他开发人员完成(因此 Web 服务形成一种 API)。

SharePoint 在整个开发环境中被大量使用。大多数项目都有一个 SharePoint 网站，包括我们的。

在我们项目的 SharePoint 网站上，我们目前有一堆关于需求、设计、利益相关者演示文稿等方面的 MS Office 文档。使所有内容保持最新是很困难的。

我们还有一个仅供开发团队使用的 SharePoint wiki，我们在其中以非结构化的方式记录事物。示例包括我们的构建脚本的组织方式、我们的测试策略、编码指南。

该软件是一个相当大的金融机构的内部应用程序。

该软件由六人团队在约 1 年的时间内开发。

开发人员仅为该项目聘请的顾问，将来将无法提供帮助(除非客户决定为此付费)。

对于如何记录此类项目，客户几乎没有指导方针。

Answer 1

我认为要记录的最重要的事情是决策。这适用于从需求到架构选择的所有内容。模块 X 的要求是什么？这些需求在架构中是如何体现的？为什么选择架构模式 A 而不是 B？有什么好处？源代码也是如此:众所周知，注释原因比注释方法好得多。

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

我们在当前项目中使用 Wiki，它运行良好。任何人(开发人员、经理和客户)都可以轻松访问它，并且历史记录可以跟踪更改，因此您可以了解更改的内容和原因。此外，我们尝试以有意义的方式记录代码并记录主要的设计决策。我们尽量不记录太多，例如小事情，因为总是很难让这些事情保持最新，而且不值得付出努力，恕我直言。