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.

01/22/2011


Dennis BrandlThink 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."



No comments
The Engineers' Choice Awards highlight some of the best new control, instrumentation and automation products as chosen by...
Each year, a panel of Control Engineering editors and industry expert judges select the System Integrator of the Year Award winners.
Control Engineering Leaders Under 40 identifies and gives recognition to young engineers who...
Learn more about methods used to ensure that the integration between the safety system and the process control...
Adding industrial toughness and reliability to Ethernet eGuide
Technological advances like multiple-in-multiple-out (MIMO) transmitting and receiving
Big plans for small nuclear reactors: Simpler, safer control designs; Smarter manufacturing; Industrial cloud; Mobile HMI; Controls convergence
Virtualization advice: 4 ways splitting servers can help manufacturing; Efficient motion controls; Fill the brain drain; Learn from the HART Plant of the Year
Two sides to process safety: Combining human and technical factors in your program; Preparing HMI graphics for migrations; Mechatronics and safety; Engineers' Choice Awards
The Ask Control Engineering blog covers all aspects of automation, including motors, drives, sensors, motion control, machine control, and embedded systems.
Join this ongoing discussion of machine guarding topics, including solutions assessments, regulatory compliance, gap analysis...
News and comments from Control Engineering process industries editor, Peter Welander.
IMS Research, recently acquired by IHS Inc., is a leading independent supplier of market research and consultancy to the global electronics industry.
This is a blog from the trenches – written by engineers who are implementing and upgrading control systems every day across every industry.
Anthony Baker is a fictitious aggregation of experts from Callisto Integration, providing manufacturing consulting and systems integration.
Integrator Guide

Integrator Guide

Search the online Automation Integrator Guide
 

Create New Listing

Visit the System Integrators page to view past winners of Control Engineering's System Integrator of the Year Award and learn how to enter the competition. You will also find more information on system integrators and Control System Integrators Association.

Case Study Database

Case Study Database

Get more exposure for your case study by uploading it to the Control Engineering case study database, where end-users can identify relevant solutions and explore what the experts are doing to effectively implement a variety of technology and productivity related projects.

These case studies provide examples of how knowledgeable solution providers have used technology, processes and people to create effective and successful implementations in real-world situations. Case studies can be completed by filling out a simple online form where you can outline the project title, abstract, and full story in 1500 words or less; upload photos, videos and a logo.

Click here to visit the Case Study Database and upload your case study.