Engineering and IT Insight – Bad project documentation: Break the habit

Improve manufacturing IT, automation, or control projects by avoiding missing, incorrect, poorly written, or incomplete documentation.

By Dennis Brandl January 23, 2011

Think you’re done with a manufacturing IT, automation, or control project? Check your documentation to avoid one of the worst bad habits of projects: Missing, incorrect, poorly written, or incomplete documentation.

Formal writing has been around since before 2800 BC, and with almost 5,000 years of experience, we should have worked out the best way to communicate knowledge. However, many projects use the equivalent of sitting around a campfire and telling stories as their primary method for communicating knowledge and reviewing designs. In modern projects the campfire is replaced by the glowing screen of a web meeting, but the concept is the same. Failure to document, missing documents, incorrect documents, poorly written documents, or the failure to review and correct documents are among the worst bad habits of unsuccessful projects. 

Documentation can be the bane of any project. A large percentage of failed projects have been blamed on bad, missing, or incorrect documentation. There are many reasons for this, but one major reason is that engineers are usually poor writers. There may be something in the engineer’s brain that is at odds with clear and effective writing skills, or it may be that engineers have not learned critical writing skills. Poor documentation habits are often accompanied by poor review habits. Many engineers don’t even know how badly they write because their documents are reviewed for technical correctness but not for completeness, clarity, and readability. You know you have this problem if a reader knows less and is more confused after reading project documentation than before reading it. 

Whatever the reason for the lack of writing skills, many project engineers (and their IT equivalents) prefer to “document” concepts and knowledge through meetings and seminars. The result is that a lot of project knowledge is kept only in people’s heads. These projects may have generated a lot of documentation, and can often be drowning in documents, but they are starved for useable knowledge.

For internal projects that are to be delivered to end users, there is no alternative to good user documentation and usable training manuals. In unsuccessful projects these documents are not part of the development plan but are planned for development “after we finish the code.” This is shortsighted behavior and will invariably lead to multiple problems later in the project, usually requiring extensive rework. Without development of these documents during the design, the usability of the product will not be known until after the code is complete. Many successful projects, including those that follow the Agile methodology, start with draft user guides and training manuals.

Technology transfer projects are especially prone to having bad documentation habits. These projects involve the technology transfer of automation systems, control strategies, recipes, and manufacturing definitions. The average technology transfer project involves shipping one or more engineers to the receiving site for weeks or months so they can install the new system and make it operational. During the project, the engineers will spend a lot of time rediscovering information that was not documented during the original development. Unfortunately, a large percentage of technology transfer projects end in failure because the original system cannot be reproduced at a different site.

How do you know if your project has this bad habit? There are some signs to look for:

  • Frequent “campfire equivalents” for information exchange, such as having engineers travel to other sites to give “information dumps”
  • No user guides to help installation and maintenance of the system
  • No one is assigned responsibility for creating user documentation
  • Document reviews without review for readability and clarity
  • No feedback mechanism for writers to improve their skills
  • Much rework because someone “missed the meeting where we talked about that.”

To fix the bad documentation habit, your project should take the attitude “if something isn’t well documented, then you may as well throw it away, because you will eventually.” No one wants to throw away work, so this attitude emphasizes the importance of usable and readable documentation. Breaking the bad documentation habit requires engineers and developers to improve their writing skills and extend their comfort zone to include the ability to write clearly and concisely.

It also requires project managers to pay attention to the readability and usability of their project’s documentation, not just the technical correctness. The bad documentation habit is a hard habit to break, but it must be broken to have a successful project. Few, if any, successful projects are without well-written and easily readable documentation. 

– Dennis Brandl is president of BR&L Consulting in Cary, NC, www.brlconsulting.com. His firm focuses on manufacturing IT. Contact him at dbrandl(at)brlconsulting.com. Edited by Mark T. Hoske, Control Engineering, www.controleng.com.

Also read:

– Engineering and IT Insight: Failure is not an option – Taking a "failure is not an option" or "do it right the first time" approach with manufacturing IT projects can hide important information and waste time, especially when workflows are in place to catch and quickly correct an occasional error.

Engineering and IT Insight – File this under: Bad habits for control engineers – Move past the file cabinet organizational mentality to improve automation system projects. This is fourth in a series of “bad habits to avoid” from the Control Engineering Engineering and IT Insight column.

Engineering and IT Insight: Are you using the wrong control system tools? – Applying the wrong tools in control system projects can be akin to using stone knives and bearskins. Which of these five misused tools are killing your productivity?

Engineering and IT Insight: Schedules for engineers – A missing or unrealistic schedule is a bad habit common to unsuccessful projects. Lack of experience in the project space can lead to ballpark estimates and schedule slippage.

IT and Engineering Insight: Control architecture, who needs it? – If you have a large control software programming project and no control system architect, small changes can lead to dead ends and bad decisions.

IT and Engineering Insight: Seven habits of unsuccessful projects – Understanding if you are in an out-of-control IT project is important. Here are some traits of failing or soon-to-fail projects. If your project has three or more of these attributes, you need a project "reboot."