项目文件？

Question

我为CMMI 5级认证公司工作，我讨厌的一件事是我们准备的文件数量（作为程序员，我已经讨厌过文件）。我们有很多很多文件，比如PID（项目启动文档），业务需求，系统需求，技术规范，代码审查清单，问题日志，缺陷日志，配置管理计划，配置管理检查表，发布文档和批次...

这些文档中有近90％只是为了QA审核而完成:) ..您认为项目最重要的文档是什么？从长远来看，其他开发人员可以使用哪些文档？

请在此分享您的良好做法。我想将它们用于我自己的项目或我计划从长远来看的公司。

由于

Answer 1

关键文档是good functional spec.系统应该有 一个且只有一个 参考文档。

每当有人更改系统或界面时，过度使用文档会激增大量的小型需求和规范文档。对于任何复杂的系统，不久你就可以将你的规范分布在几百个单词，excel，visio甚至powerpoint文件中。如果发生这种情况，您将无法确定当前的内容，甚至是否找到并确定了所有相关文档。

BRD-SRD-Tech规范进展是基于业务签署BRD的假设，业务分析师根据BRD中记录的要求签署SRD并且技术规范与SRD签署。这会生成一个签名网络，多个包含冗余信息的文档，使规范文档保持最新变得困难和笨拙。

正因为如此，后续的需求文档往往采取一系列变更请求和补充要求以及规范文档的形式，每个都有自己的签名和审计流程。您获得了CYA和审计跟踪（或至少是审计跟踪的外观），但您失去了清晰度。现在没有关于该系统的明确参考文件，并且很难确定任何特定活动的当前或相关内容。最终结果是您的业务分析过程陷入了法医研究的困境，这增加了交付计划的开销和延迟。

规范文档的构建方式应该是任何给定系统或子系统都有一个明确的引用。该文件应保持最新和版本。获得good technical documentation tool Framemaker,之类的{{3}}，这样您的流程就可以扩展，并且该文档具有一些缺乏Word的结构完整性。

Answer 2

对我而言，我使用的唯一真实文件是规范。越详细越好。然而，它不需要一次完成所有，并且它不需要特别正式。对我来说，比检查和签名以及双重检查和双重签名的文档总是能够获得最新版本的文档更有用。能够与人们谈论他们所写的内容，并在任何模棱两可的情况下做出决定。这对我来说比其他任何东西都有用。

总结：规范是我发现的唯一有用的文档，但与让项目经理了解内部提出的系统相比，它相形见绌，并且能够根据他们所知道的内容做出合理的决策。

Answer 3

文件就像豆腐 - 大多数人都讨厌它，直到他们意识到在合适的条件下它才会真的很好。

问题是您认为文档的内容主要是出于文档的考虑。作为开发人员，您在所生成的文档中看不到任何直接价值，因为您知道如果没有您要求的所有TPS报告，您可以完成工作。

不幸的是，我要打赌，在一家你一直被迫吃生豆腐的公司里，你无法做很多事情。您可能只需要填写并编写公司所需的文档，但您至少可以做一件事......您可以编写至少对您有用的文档，以及您可以将它们与您的代码一起传递给维护它的其他人。

除了内联文档之外，您还可以设置一个wiki供自己和团队成员使用。这种类型的文档是可搜索的，这对开发人员来说已经是一个很大的优势，而且它更像是一个活文档，而不是你必须写的类似家庭作业的文件。您已经发布到SO，所以只需将您的文档视为将您的知识集中在一个更有用的地方。

Answer 4

  

您认为项目最重要的文件是什么？

不同的人有不同的需求：例如，所有者需要的文件（例如商业合同）与QA所需的文件不同。

  

另一位开发者长期可以使用哪些文件？

IMO最重要的文件（源代码除外）是功能规范：因为该软件假设要做什么（而不是 ）做）是一件不一定是逆向工程的东西。另请参阅How does a good developer keep from creating code with a low bus hit factor?

Answer 5

用户故事，燃尽图，代码

Answer 6

从项目的角度来看，最重要的文件是通常包含计划一词的文件，例如项目计划，配置管理计划，质量计划等。

您所描述的内容在流程改进中很常见，通常会对两个主要原因做出响应。一个是系统真的是过度使用并阻碍了正在进行的实际工作。另一个问题实际上是在您的问题中回答的：并不是文档只是为了审计而完成，而您的重点不仅仅是对其他开发人员的文档有用，而是对项目或整个公司有用。

人们通常从自己的角度看待事物，有时候需要看一般情况。

Answer 7

我是旧4 + 1观点的粉丝：

• 使用案例视图（a / k / a用户素材）。有几种形式：正确的使用案例，没有明确定义的前瞻性用例和需要分解的史诗。

• 逻辑视图。 “静态”视图。 UML类图等在这里作为设计文档很好地工作。这还包括各种协议的请求和响应格式。这是我们记录RESTful请求和响应的地方。这包括REST URI设计。

• 流程视图。 “动态”视图。用于设计文档的UML活动图，序列图和状态图等。在某些情况下，简单的叙述效果很好。在其他情况下，有一个 State 设计模式，它需要结合使用类图和状态图来显示有状态对象的交互方式。

  这还包括协议（例如REST）。这是我们为各种REST请求定义任何特殊处理的地方。

  这还包括身份验证或授权规则，以及安全性，日志记录等任何其他交叉方面。

• 组件视图。我们正在为部署而构建的部分。这包括我们依赖的东西，模块和包的结构等。这通常是一个简单的组件图或组件及其依赖项列表。

• 部署视图。我们尝试从部署的代码中生成此内容。由于我们使用的是Python，因此我们使用epydoc来创建API文档。我们还使用Sphinx将模块文档导入到该软件视图中。

  这还包括参数，设置和配置详细信息。

然而，这还不够。

当项目开始时，你必须通过一系列冲刺来解决这个问题。

1. 第一个sprint只构建用例视图。

2. 后续冲刺构建了一个“架构”来实现用例。体系结构文档具有4 + 1个视图，但处于高级抽象级别。它总结了模型模式的结构，请求和回复，RESTful处理，其他处理，预期的组件等。它从未有过部署视图。我们通常将操作员指南和API文档作为体系结构的部署视图。

3. 然后，设计和构造冲刺为各种组件构建（和更新）详细的4 + 1视图文档。

4. 然后发布sprint构建（并更新）部署视图。