12

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

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

请在这里分享您的良好做法。我想将它们用于我自己的项目或我计划长期创办的公司。

谢谢

4

7 回答 7

11

关键文件是一个很好的功能规范。 一个系统应该只有一个参考文档。

每当有人更改系统或界面时，过度的文档就会激增大量的小需求和规范文档。对于任何复杂的系统，不久之后您的规范就会分布在数百个各种单词、excel、visio 甚至是 powerpoint 文件中。发生这种情况时，您会不清楚什么是最新的，甚至您是否已经找到并识别了所有相关文档。

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

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

规范文档应该以这样一种方式构建，即任何给定的系统或子系统都有一个明确的参考。该文档应保持最新并进行版本控制。获得像Framemaker这样好的技术文档工具，这样您的流程就可以扩展，并且文档具有 Word 所缺乏的那种结构完整性。

于 2009-02-10T16:47:20.603 回答
4

对我来说，我唯一使用过的真实文档是规范。越详细越好。不过不需要一次性全部完成，也不需要特别正式。对我来说，比经过检查和签名以及双重检查和双重签名的文档更有用的是始终能够获得最新版本的文档。并且能够与人们谈论他们所写的内容，并在有任何歧义的情况下做出决定。这对我来说比其他任何东西都更有用。

总而言之：规范是我发现的唯一有用的文档，但是与拥有一个完全了解所提议系统的项目经理相比，它相形见绌，并且可以根据他们所知道的做出明智的决定。

于 2009-02-10T16:48:00.510 回答
2

文档就像豆腐——大多数人讨厌它，直到他们意识到在适当的条件下，它可能真的很好。

问题是您认为文档主要是为了文档而制作的。作为开发人员，您不会在您生成的文档中看到任何直接价值，因为您知道您可以在没有您需要制作的所有 TPS 报告的情况下完成您的工作。

不幸的是，我敢打赌，在一家你一直被迫吃生豆腐的公司里，你无能为力。您可能只需要吸收它并编写公司需要的文档，但是您至少可以做一件事……您可以编写至少对您有用的文档，并且可以将它们与您的其他维护它的人的代码。

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

于 2009-02-10T17:06:27.830 回答
1

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

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

从长远来看，其他开发人员可以使用哪些文档？

IMO 最重要的文档（源代码除外）是功能规范：因为软件应该做什么（而不是它正在做什么）是一件事，不一定是逆向工程。另请参阅优秀的开发人员如何避免创建总线命中率低的代码？

于 2009-02-10T16:48:30.227 回答
1

用户故事、燃尽图、代码

于 2009-02-10T16:49:53.953 回答
1

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

您所描述的内容在流程改进中很常见，并且通常响应两个主要原因。一是该系统确实是过度教育并妨碍了正在完成的实际工作。您的问题实际上回答了另一个问题：并非只是为了审计而编写文件，您的重点不应该只是文档对其他开发人员有多大用处，而应该是对项目或整个公司有用。

一个人通常从自己的角度看事情，有时需要看大局。

于 2009-02-10T16:50:21.660 回答
1

我是旧的 4+1 视图的粉丝：

  • 用例视图（a/k/a 用户故事）。有几种形式：正确的用例、没有很好定义的前瞻性用例和需要分解的史诗。

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

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

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

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

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

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

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

然而，这还不够。

当项目开始时，您必须通过一系列冲刺来完成这一目标。

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

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

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

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

于 2009-02-11T12:56:02.917 回答