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

No comments
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.
The Engineering Leaders Under 40 program identifies and gives recognition to young engineers who...
Your leaks start here: Take a disciplined approach with your hydraulic system; U.S. presence at Hannover Messe a rousing success
Hannover Messe 2016: Taking hold of the future - Partner Country status spotlights U.S. manufacturing; Honoring manufacturing excellence: The 2015 Product of the Year Winners
Inside IIoT: How technology, strategy can improve your operation; Dry media or web scrubber?; Six steps to design a PM program
Getting to the bottom of subsea repairs: Older pipelines need more attention, and operators need a repair strategy; OTC preview; Offshore production difficult - and crucial
Digital oilfields: Integrated HMI/SCADA systems enable smarter data acquisition; Real-world impact of simulation; Electric actuator technology prospers in production fields
Special report: U.S. natural gas; LNG transport technologies evolve to meet market demand; Understanding new methane regulations; Predictive maintenance for gas pipeline compressors
Warehouse winter comfort: The HTHV solution; Cooling with natural gas; Plastics industry booming
Managing automation upgrades, retrofits; Making technical, business sense; Ensuring network cyber security
Designing generator systems; Using online commissioning tools; Selective coordination best practices

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.
This article collection contains several articles on the vital role that compressed air plays in manufacturing plants.
This article collection contains several articles on the Industrial Internet of Things (IIoT) and how it is transforming manufacturing.
This article collection contains several articles on strategic maintenance and understanding all the parts of your plant.
click me