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
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.
Control noise, vibration in building design: Tackling acoustics and design issues; High-performance building design; NFPA 99; Combined heat, power
40 Under 40; Stand-alone medical buildings; NFPA 92; Specialty fire suppression; Applying 90.1 in lighting design
2016 Product of the Year Finalists: Vote now; Data center Q&A; LED codes; Smart buildings
Putting COPS into context; Designing medium-voltage electrical systems; Planning and designing resilient, efficient data centers; The nine steps of designing generator fuel systems
Designing generator systems; Using online commissioning tools; Selective coordination best practices
Understanding transfer switch operation; Coordinating protective devices; Analyzing NEC 2014 changes; Cooling data centers
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.
click me