工程和IT洞察:保持文档与代码同步

基于高度乐观的完美期望(HOPE)推迟软件文档并不是一个成功的项目策略。链接到所有不成功项目的7个坏习惯。

通过丹尼斯Brandl 2011年2月18日

不让工程项目的用户、设计和测试文档与软件代码保持同步是我列出的“不成功项目的7个坏习惯”中的最后一个坏习惯。虽然在这一点上的疏忽会降低工程的有用性或其感知价值，但这是项目管理的坏习惯，而不是工程问题。当文档与要测试的系统或要交付的系统不同步时，就会出现这种坏习惯。

软件密集型的制造项目与大多数其他工程项目不同，因为在最终产品几乎完成之前，您无法“看到”它。最终用户和审查人员不能评估最终产品，直到它可以勉强运行。运行糟糕(有时更小)的项目不会构建最终用户和审查人员可以看到和评估的模型或原型。在项目的大部分时间里(通常超过项目进度的80%)，文档是唯一可用于支持评审的工件。设计文档、用户指南、安装手册和帮助文件形式的文档为最终用户和beta测试人员提供了一个了解项目的窗口，他们需要在更改太迟之前评估系统。如果我们在房屋建造中遇到同样的情况，买方将无法在搬迁日之前检查楼层平面图，在这个时候，建筑商将有很大的希望满足买方的期望。没有文档，我们只能希望交付的系统是正确的。

失去了知识

在项目的编码阶段，实现者将做出许多决策，当需要编写文档时，这些决策很容易被遗忘。例如，可能有一个假设，实现者使timer1必须比timer2快，但是这个假设可以被遗忘，直到最终用户错误地配置了系统，或者实现者设计了一个系统，其中选项a、B和D不能全部被选择，但其他组合是有效的。这些小的实现决策通常不会在需求中被捕获，通常在设计时不完全了解，并且，在不成功的项目中，在编制文档时被遗忘。

无法保持代码和文档同步也会严重影响扩展或附加项目。许多项目被认为是失败的，不是因为它们没有满足规定的需求，而是因为当在初始部署时发现真正的需求时，它们不能被降级。如果代码与文档不匹配，那么更新可能会非常昂贵或遇到不必要的困难。

检查尊重

没有记录是项目管理的失败。项目管理人员将决定不检查文档，因此开发人员和编码员将认为它不重要。如果你是一个项目经理，那么你必须遵循这句话:“人们尊重你检查的东西。”项目经理必须检查和评估文档，将它们包括在项目进度表中，将检查时间包括在进度表中，并使开发人员负责生成文档。在不成功的项目中，开发人员不负责生成文档，任务可能被分配给非专家。这意味着那些知道设计决策的细节和结果的人不负责保存这些信息，而那些不知道的人必须尝试发现这些知识，这是引入错误的机会。

并不是所有的项目都需要在编写代码之前编写相同级别的文档。在瀑布式方法中，所有的文档在编码之前都是必需的，但是as-is更新通常在代码完成很久之后才完成。如果您正在使用这种项目方法，那么文档应该在编码阶段更新，而不是在编码之后更新。使用敏捷或SCRUM方法，用户文档和设计文档应该在每个设计/代码/测试周期完成的同时交付。

推迟会增加风险

您可以决定推迟文档开发，但必须将其视为项目风险。如果项目团队很好地理解了问题和解决方案(不是在公司或行业内理解，而是由实际的团队成员理解)，并且团队成员亲自在类似的项目中工作过，那么风险可能是合理的，但仍然存在风险。如果这些条件不满足，那么决定推迟文档编制是基于HOPE(高度乐观的完美期望)。虽然希望是一件美好的事情，但它是糟糕的项目策略。如果没有文档所提供的对交付项目的可见性，项目经理只能希望构建并交付正确的软件。很少有团队具有使用HOPE作为策略所需的经验和信任水平，因此，如果您的所有项目都延迟编写文档，那么您就有代码和文档不同步的坏习惯。

可见成本，时间

确定您是否有这种坏习惯很容易:检查用户指南、安装指南和帮助文件是否包含在项目计划中，在代码发布之前可用，并分配了资源。纠正这个问题也很容易:将文档添加到日程安排中并分配资源。纠正这个坏习惯最困难的地方在于:

使项目的全部成本和时间可见
需要改变使用交付代码作为项目进度度量的思维模式
要求那些拥有相关知识的人负责记录他们的工作。

虽然专业技术作者当然可以帮助创建文档，但他们不应该负责获取开发人员和编码员的知识。

编写良好和正确的文档应该占项目工作的20%，但不应该是在资源或日程紧张时被削减的20%。通常，最不成功的软件项目是那些只交付代码，而没有为支持人员、最终用户和后续设计工作提供足够的文档的项目。一个项目的成功必须在满足正式需求的同时，以可用性和可扩展性来衡量。在文档上的吝啬已经把许多技术上成功的项目变成了最终用户的失败和不成功的项目。不要陷入这个坏习惯，把你的成功仅仅建立在hope——高度乐观的完美期望上。

- Dennis Brandl是北卡罗来纳州Cary BR&L咨询公司的总裁。他的公司专注于IT制造业。请通过dbrandl@brlconsulting.com联系他。由Mark T. Hoske编辑，控制工程，www.globalelove.com。