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 2013 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...
The true cost of lubrication: Three keys to consider when evaluating oils; Plant Engineering Lubrication Guide; 11 ways to protect bearing assets; Is lubrication part of your KPIs?
Contract maintenance: 5 ways to keep things humming while keeping an eye on costs; Pneumatic systems; Energy monitoring; The sixth 'S' is safety
Transport your data: Supply chain information critical to operational excellence; High-voltage faults; Portable cooling; Safety automation isn't automatic
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.

Maintaining low data center PUE; Using eco mode in UPS systems; Commissioning electrical and power systems; Exploring dc power distribution alternatives
Synchronizing industrial Ethernet networks; Selecting protocol conversion gateways; Integrating HMIs with PLCs and PACs
Why manufacturers need to see energy in a different light: Current approaches to energy management yield quick savings, but leave plant managers searching for ways of improving on those early gains.

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.