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 Top Plant program honors outstanding manufacturing facilities in North America. View the 2013 Top Plant.
The Product of the Year program recognizes products newly released in the manufacturing industries.
The Leaders Under 40 program features outstanding young people who are making a difference in manufacturing. View the 2013 Leaders here.
The new control room: It's got all the bells and whistles - and alarms, too; Remote maintenance; Specifying VFDs
2014 forecast issue: To serve and to manufacture - Veterans will bring skill and discipline to the plant floor if we can find a way to get them there.
2013 Top Plant: Lincoln Electric Company, Cleveland, Ohio
Case Study Database

Case Study Database

Get more exposure for your case study by uploading it to the Plant 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.

Bring focus to PLC programming: 5 things to avoid in putting your system together; Managing the DCS upgrade; PLM upgrade: a step-by-step approach
Balancing the bagging triangle; PID tuning improves process efficiency; Standardizing control room HMIs
Commissioning electrical systems in mission critical facilities; Anticipating the Smart Grid; Mitigating arc flash hazards in medium-voltage switchgear; Comparing generator sizing software

Annual Salary Survey

Participate in the 2013 Salary Survey

In a year when manufacturing continued to lead the economic rebound, it makes sense that plant manager bonuses rebounded. Plant Engineering’s annual Salary Survey shows both wages and bonuses rose in 2012 after a retreat the year before.

Average salary across all job titles for plant floor management rose 3.5% to $95,446, and bonus compensation jumped to $15,162, a 4.2% increase from the 2010 level and double the 2011 total, which showed a sharp drop in bonus.

2012 Salary Survey Analysis

2012 Salary Survey Results

Maintenance and reliability tips and best practices from the maintenance and reliability coaches at Allied Reliability Group.
The One Voice for Manufacturing blog reports on federal public policy issues impacting the manufacturing sector. One Voice is a joint effort by the National Tooling and Machining...
The Society for Maintenance and Reliability Professionals an organization devoted...
Join this ongoing discussion of machine guarding topics, including solutions assessments, regulatory compliance, gap analysis...
IMS Research, recently acquired by IHS Inc., is a leading independent supplier of market research and consultancy to the global electronics industry.
Maintenance is not optional in manufacturing. It’s a profit center, driving productivity and uptime while reducing overall repair costs.
The Lachance on CMMS blog is about current maintenance topics. Blogger Paul Lachance is president and chief technology officer for Smartware Group.