Engineering and IT Insight: Keep documentation in sync with code

Deferring software documentation based on highly optimistic perfection expectations (HOPE) is not a successful project strategy. Link to all 7 Bad Habits of Unsuccessful Projects.


Not keeping an engineering project’s user, design, and test documents up to date with software code is the last bad habit in my short list of the 7 Bad Habits of Unsuccessful Projects (see links below). While slipping on this point detracts from usefulness of the engineering or its perceived value, it is a project management bad habit and not an engineering problem. This bad habit occurs when documents are not in sync with a system to be tested or a system to be delivered.

Manufacturing projects that are software intensive differ from most other engineering projects because you can’t “see” the final product until it is almost complete. End users and reviewers cannot evaluate the final product until it becomes marginally operational. Poorly run (and sometimes smaller) projects don’t build models or prototypes that end users and reviewers can see and evaluate. During most of the project (often more than 80% of the project schedule), documents are the only artifacts available to support reviews. Documentation in the form of design documents, user guides, installation manuals, and help files provide end users and beta-testers a window into the project that they need to evaluate the system before it is too late to change. If we had the same situation in home construction, the buyer would be unable to check the floor plan until moving day, at which time there would be a lot of hope the builder met buyer expectations. Without documentation, there’s only hope that the delivered system is correct.

Lost knowledge

In the coding phase of a project the implementer will make a lot of decisions that can easily be forgotten when it is time to document. For example, there may be an assumption that the implementer makes that timer1 must be faster than timer2, but this assumption can be forgotten until an end user misconfigures the system, or the implementer designs a system in which options A, B, and D cannot all be selected, but other combinations are valid. These small implementation decisions are usually not captured in requirements, often not fully known at design time, and, in unsuccessful projects, forgotten at documentation time.

Failure to keep the code and documentation in sync will also seriously impact extensions or add-on projects. Many projects are considered failures, not because they don’t meet the stated requirements, but because they can’t be ungraded when the real requirements are discovered at the initial deployment. If the code does not match the documentation, then updates can be expensive or unnecessarily difficult.

Inspect for respect

Failure to document is a project management failure. Project management will have decided not to inspect documentation, so developers and coders will not consider it important. If you are a project manager, then you must live by the saying, “People respect what you inspect.” Project managers must inspect and evaluate documents, include them in the project schedule, include inspection time in the schedule, and make developers responsible for generating the documentation. In unsuccessful projects the developers are not responsible for generating documentation, and the task may be assigned to non-experts. This means that those who know the details and consequences of design decisions are not responsible for preserving that information, and those who don’t know must attempt to discover the knowledge, which is an opportunity to introduce errors.

Not all projects will require the same level of documentation prior to code. In waterfall methodologies all documentation is required prior to coding, but as-is updates are often completed long after the code is complete. If you are using this project methodology, then documents should be updated during the coding phase, and not after. With Agile or SCRUM methodologies, user documentation and design documents should be delivered the same time each design/code/test cycle is completed.

Deferring adds risk

You can decide to defer documentation development, but it must be considered a project risk. If the problem and solutions are personally well understood by the project team (not understood within the company or industry, but understood by the actual team members), and the team members have personally worked on similar projects, then the risk may be justified, but there is still a risk. If these conditions are not meet, then deciding to defer documentation is based on HOPE (highly optimistic perfection expectations). While hope is a wonderful thing to have, it is terrible project strategy. Without visibility into the delivered project that documentation provides, the project manager can only hope that the correct software is built and delivered. Few teams have the level of experience and trust required to use HOPE as a strategy, so if all of your projects are deferring documentation, than you have the bad habit of out-of-sync code and documents.

Visible costs, time

Determining if you have this bad habit is easy: Check if user guides, installation guides, and help files are included in the project schedule, available prior to code release, and have assigned resources. Correcting the problem is also easy: Add the documents to the schedule and assign resources. The most difficult parts about correcting this bad habit are that it:

  • Makes the full cost and time of the project visible
  • Requires a change to the mind-set that uses delivered code as the measure of a project’s progress, and
  • Requires that those who have the knowledge are responsible for documenting their work.

While professional technical writers certainly can assist in creating documentation, they should not be responsible for capturing developer and coder knowledge.

Well-written and correct documentation should take about 20% of a project’s effort, but it should not be the 20% that is cut when resources or schedules are tight. Often the most unsuccessful software projects are those that deliver only code and no adequate documentation for support staff, end users, and to followup design efforts. Success in a project must be measured on usability and extensibility as much as meeting formal requirements. Scrimping on documentation has turned many technological successful projects into end user failures and unsuccessful projects. Don’t fall into this bad habit by basing your success only on HOPE—highly optimistic perfection expectations.

- Dennis Brandl is president of BR&L Consulting in Cary, NC. His firm focuses on manufacturing IT. Contact him at Edited by Mark T. Hoske, Control Engineering,

Also read:

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.

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 work flows 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."

The Top Plant program honors outstanding manufacturing facilities in North America. View the 2015 Top Plant.
The Product of the Year program recognizes products newly released in the manufacturing industries.
Each year, a panel of Control Engineering and Plant Engineering editors and industry expert judges select the System Integrator of the Year Award winners in three categories.
Pipe fabrication and IIoT; 2017 Product of the Year finalists
The future of electrical safety; Four keys to RPM success; Picking the right weld fume option
A new approach to the Skills Gap; Community colleges may hold the key for manufacturing; 2017 Engineering Leaders Under 40
Control room technology innovation; Practical approaches to corrosion protection; Pipeline regulator revises quality programs
The cloud, mobility, and remote operations; SCADA and contextual mobility; Custom UPS empowering a secure pipeline
Infrastructure for natural gas expansion; Artificial lift methods; Disruptive technology and fugitive gas emissions
Power system design for high-performance buildings; mitigating arc flash hazards
VFDs improving motion control applications; Powering automation and IIoT wirelessly; Connecting the dots
Natural gas engines; New applications for fuel cells; Large engines become more efficient; Extending boiler life

Annual Salary Survey

Before the calendar turned, 2016 already had the makings of a pivotal year for manufacturing, and for the world.

There were the big events for the year, including the United States as Partner Country at Hannover Messe in April and the 2016 International Manufacturing Technology Show in Chicago in September. There's also the matter of the U.S. presidential elections in November, which promise to shape policy in manufacturing for years to come.

But the year started with global economic turmoil, as a slowdown in Chinese manufacturing triggered a worldwide stock hiccup that sent values plummeting. The continued plunge in world oil prices has resulted in a slowdown in exploration and, by extension, the manufacture of exploration equipment.

Read more: 2015 Salary Survey

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.
The maintenance journey has been a long, slow trek for most manufacturers and has gone from preventive maintenance to predictive maintenance.
This digital report explains how plant engineers and subject matter experts (SME) need support for time series data and its many challenges.
This digital report will explore several aspects of how IIoT will transform manufacturing in the coming years.
Maintenance Manager; California Oils Corp.
Associate, Electrical Engineering; Wood Harbinger
Control Systems Engineer; Robert Bosch Corp.
This course focuses on climate analysis, appropriateness of cooling system selection, and combining cooling systems.
This course will help identify and reveal electrical hazards and identify the solutions to implementing and maintaining a safe work environment.
This course explains how maintaining power and communication systems through emergency power-generation systems is critical.
click me