项目的文档？

Question

我在一家CMMI5级认证的公司工作，我讨厌的一件事是我们准备了大量的文档(作为一个程序员，我已经讨厌文档了)。我们有大量的文档，如PID(项目启动文档)、业务需求、系统需求、技术规范、代码评审检查表、问题日志、缺陷日志、配置管理计划、配置管理检查表、发布文档和批次...

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

请在这里分享你的良好实践。从长远来看，我想把它们用于我自己的项目或我计划开始的公司。

谢谢

Answer 1

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

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

BRD - SRD -技术规范进展基于以下假设:业务人员签署BRD，业务分析师根据BRD中记录的要求签署SRD，技术规范签署SRD。这就产生了一个网络签名，多个文档的冗余信息，并使其难以和笨拙地保持规范文档的最新。

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

规范文档应该以这样的方式构建，即任何给定的系统或子系统都有一个明确的参考。应该保持文档的最新版本和版本。获得一个像Framemaker,这样的good technical documentation tool，这样您的流程就可以扩展，并且文档具有Word所缺少的某种结构完整性。

Answer 2

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

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

Answer 3

文档就像豆腐--大多数人讨厌它，直到他们意识到在正确的条件下，它可以真正地变得很好。

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

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

除了内联文档之外，您还可以设置一个wiki，供您自己和团队中的人使用。这种类型的文档是可搜索的，这对开发人员来说已经是一个很大的优势，而且它更像是一个活文档，而不是你必须写的作业一样的论文。你已经在SO上发过帖子了，所以把你的文档看作是将你的知识汇集在一个更有用的地方。