工程和IT洞察——糟糕的项目文档:改掉这个习惯

认为您已经完成了一个制造IT、自动化或控制项目?检查您的文档，以避免项目中最坏的坏习惯之一:缺少、不正确、书写糟糕或不完整的文档。

正式的书写早在公元前2800年就已经出现了，凭借近5000年的经验，我们应该已经找到了交流知识的最佳方式。然而，许多项目使用围坐在篝火旁讲故事作为他们交流知识和审查设计的主要方法。在现代项目中，篝火被网络会议的发光屏幕所取代，但概念是相同的。没有记录文档、缺少文档、不正确的文档、写得不好的文档，或者没有检查和更正文档都是不成功项目的坏习惯。

文档可能是任何项目的克星。很大一部分失败的项目被归咎于糟糕的、缺失的或不正确的文档。造成这种情况的原因有很多，但其中一个主要原因是工程师通常不擅长写作。工程师的大脑中可能存在一些与清晰有效的写作技能不一致的东西，或者工程师没有学习批判性的写作技能。不良的文档习惯往往伴随着不良的回顾习惯。许多工程师甚至不知道他们写得有多糟糕，因为他们的文档只审查技术正确性，而不是完整性、清晰度和可读性。如果读者在阅读项目文档后比阅读之前知道的更少，并且更困惑，那么你就知道你有这个问题。

无论缺乏写作技能的原因是什么，许多项目工程师(以及他们的IT对等人员)更喜欢通过会议和研讨会来“记录”概念和知识。其结果是，许多项目知识只保存在人们的头脑中。这些项目可能已经生成了大量的文档，并且经常淹没在文档中，但是它们缺乏可用的知识。

对于要交付给最终用户的内部项目，除了良好的用户文档和可用的培训手册外，没有其他选择。在不成功的项目中，这些文档不是开发计划的一部分，而是计划在“我们完成代码之后”进行开发。这是一种目光短浅的行为，在项目后期必然会导致多个问题，通常需要大量的返工。如果在设计过程中没有开发这些文档，产品的可用性将在代码完成后才能知道。许多成功的项目，包括那些遵循敏捷方法的项目，都是从用户指南草案和培训手册开始的。

技术转让项目特别容易有不良的文件编制习惯。这些项目涉及自动化系统、控制策略、配方和制造定义的技术转移。一般的技术转让项目都涉及派遣一名或多名工程师到接收地点，花费数周或数月时间安装新系统并使其投入使用。在项目期间，工程师将花费大量时间重新发现原始开发期间没有记录的信息。不幸的是，很大比例的技术转让项目以失败告终，因为原来的系统不能在不同的地点重现。

您如何知道您的项目是否有这种坏习惯呢?以下是一些值得注意的迹象:

• 频繁的“篝火对等物”进行信息交换，例如让工程师前往其他站点提供“信息转储”
• 无系统安装和维护的用户指南
• 没有人被分配创建用户文档的责任
• 文档审查，而不审查可读性和清晰度
• 没有反馈机制来提高作者的技能
• 大量返工，因为有人“错过了我们讨论这个问题的会议”。

为了纠正不良的文档习惯，您的项目应该采取这样的态度:“如果某些东西没有很好地记录，那么您不妨将其丢弃，因为您最终会这样做。”没有人愿意放弃工作，所以这种态度强调了可用和可读的文档的重要性。打破坏的文档习惯要求工程师和开发人员提高他们的写作技能，并扩展他们的舒适区，包括清晰简洁的写作能力。

它还要求项目经理注意项目文档的可读性和可用性，而不仅仅是技术上的正确性。编写文档的坏习惯很难改掉，但是要想有一个成功的项目，就必须改掉这个坏习惯。成功的项目很少(如果有的话)没有编写良好且易于阅读的文档。

- Dennis Brandl是北卡罗来纳州Cary BR&L咨询公司的总裁，网址是www.brlconsulting.com。他的公司专注于IT制造业。通过dbrandl(at)brlconsulting.com联系他。马克·霍斯克编辑，控制工程，www.globalelove.com．

还读:

-工程和IT洞察:失败不是一种选择-在制造IT项目中采取“失败不是一种选择”或“第一次就做对”的方法可能会隐藏重要信息和浪费时间，特别是当工作流程已经到位，可以捕捉并快速纠正偶尔的错误时。

- - - - - -工程和IT洞察-将此归类为:控制工程师的坏习惯-超越文件柜组织思维来改进自动化系统项目。这是控制工程工程和IT洞察专栏“要避免的坏习惯”系列中的第四个。

- - - - - -工程和IT洞察:您是否使用了错误的控制系统工具?在控制系统项目中使用错误的工具可能类似于使用石刀和熊皮。以下五种被滥用的工具中，哪一种正在扼杀你的效率?

- - - - - -工程和IT洞察:工程师的时间表缺少或不切实际的计划是一个坏习惯，通常是失败的项目。缺乏项目空间方面的经验可能会导致粗略的估计和进度下滑。

- - - - - -IT和工程洞察:控制架构，谁需要它?-如果你有一个大型的控制软件编程项目，而没有控制系统架构师，微小的更改可能导致死胡同和错误的决策。

- - - - - -IT和工程洞察:不成功项目的七个习惯了解你是否处于一个失控的IT项目是很重要的。以下是失败或即将失败项目的一些特征。如果您的项目有三个或三个以上的属性，那么您需要重新启动项目。

您是否具有本内容中提到的主题的经验和专业知识?你应该考虑为我们的CFE媒体编辑团队做出贡献，并获得你和你的公司应得的认可。点击在这里开始这个过程。