Keeping Your Documentation Current

I sat through a demo the other day of a software application that extracts all the information from your control system and puts it into an offline readable format that the user can query to create custom reports. While it is a wonderfully done package, it would be absolutely useless in many of the plants I’ve visited recently. Most of those plants are in the process of migrating their existing obsolete systems to a platform with current technology. While you might think a package like the one I saw would be perfect for documenting the before state of the migration, in reality it only covers the DCS or PLC in a lot of facilities. The problem is the number of things external to the control system have continued to evolve with time and often aren’t reflected in the online documentation. Of course that assumes the facility even has online documentation of their loop sheets, installation details, panel drawings, and so on. Even those that do have these drawing online may not have kept them current.

The migration project I’m working on right now is with one of those rare companies that actually makes a concerted effort to keep its documents current, but its engineers have still had to field verify some of what we’re migrating. Their DCS has dead code that may or may not be labeled as such, but it was left in the controller in case they wanted to use it again. The wiring drawings are in electronic format, but as with the DCS, may or may not reflect that they removed a device and left the wiring in place “just in case.” Many of these evolutionary changes to control systems are driven by unplanned events that require a quick fix. Something fails late on a Friday night and the technicians get what they can from shop stores to get them back up and running and, at best, a print of the loop gets red-lined to reflect the change. This is not a slam at the technicians or even at operations who just wanted it fixed ASAP. It’s simply the reality of a 24/7 operation with limited staffing.

I’d like to say I have the magic bullet, but I don’t. What I do have are some suggestions for those of you who are migrating your legacy systems to something new.

Step one: Pick a documentation product that will meet needs of your management of change process. Don’t have a MOC process? Write one!

Step two: Once you’ve purchased your documentation product, import everything into it that you do have in electronic format. If necessary, pay the company you bought the product from to do the importing, though you lose valuable experience in using the product if you do. The better people understand how to work with the new tool, the more likely they are to use it in the future.

Step three: Write a paragraph into your specifications that each migration project shall be documented using that tool while all code being migrated is removed from the legacy system. Leaving dead code in place is a good way to cause confusion on future projects, as I’ve seen with the one I’m doing now.

Step four: Make sure that everything associated with each of the migration projects is documented, not just the code.

If you take these steps, you’ll at least be on the path to having something you can rely on in the future, but there’s a lot more to do to ensure that it stays updated. Otherwise, if you’ve implemented a migration, how did you make sure you caught everything?

This post was written by Bruce Brandt. Bruce is the DeltaV technology leader at MAVERICK Technologies, a leading system integrator providing industrial automation, operational support and control systems engineering services in the manufacturing and process industries. MAVERICK delivers expertise and consulting in a wide variety of areas including industrial automation controls, distributed control systems, manufacturing execution systems, operational strategy, and business process optimization. The company provides a full range of automation and controls services – ranging from PID controller tuning and HMI programming to serving as a main automation contractor. Additionally MAVERICK offers industrial and technical staffing services, placing on-site automation, instrumentation and controls engineers.

Do you have experience and expertise with the topics mentioned in this content? You should consider contributing to our CFE Media editorial team and getting the recognition you and your company deserve. Click here to start this process.