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
Consulting-Specifying Engineer's Product of the Year (POY) contest is the premier award for new products in the HVAC, fire, electrical, and...
Consulting-Specifying Engineer magazine is dedicated to encouraging and recognizing the most talented young individuals...
The MEP Giants program lists the top mechanical, electrical, plumbing, and fire protection engineering firms in the United States.
High-performance buildings; Building envelope and integration; Electrical, HVAC system integration; Smoke control systems; Using BAS for M&V
Pressure piping systems: Designing with ASME; Lab ventilation; Lighting controls; Reduce energy use with VFDs
Smoke control: Designing for proper ventilation; Smart Grid Standard 201P; Commissioning HVAC systems; Boilers and boiler systems
Case Study Database

Case Study Database

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

Protecting standby generators for mission critical facilities; Selecting energy-efficient transformers; Integrating power monitoring systems; Mitigating harmonics in electrical systems
Commissioning electrical systems in mission critical facilities; Anticipating the Smart Grid; Mitigating arc flash hazards in medium-voltage switchgear; Comparing generator sizing software
Integrating BAS, electrical systems; Electrical system flexibility; Hospital electrical distribution; Electrical system grounding
Cannon Design’s blog is a place for the many voices of the firm to share thoughts and news related to current projects...
As brand protection manager for Eaton’s Electrical Sector, Tom Grace oversees counterfeit awareness...
Amara Rozgus is chief editor and content manager of Consulting-Specifier Engineer magazine.
IEEE power industry experts bring their combined experience in the electrical power industry...
Michael Heinsdorf, P.E., LEED AP, CDT is an Engineering Specification Writer at ARCOM MasterSpec.