We celebrated our 15th anniversary last year by republishing some of our more timeless content. It was really well received, so we decided to do it again from time to time. Here’s one of two sidebar stories from the tutorial article, "Design for Maintainability," first published in August 2002.
Documentation is extremely important in achieving good maintainability. This is particularly true as the complexity and sophistication of the system increases.
Documentation is a matter of discipline, which, unfortunately, many engineering and maintenance systems do not have. It comes in many forms — user, vendor, third-party and, not surprisingly, in the heads of maintenance and engineering people.
Documentation has different functionalities. Installation documentation, while it may have some overlap, is not the same as maintenance documentation. Companies need to be sure that maintenance documentation needs are being met.
Adhering to standard drawing organization, style, formats, symbols, and level and type of information provided can make life easier for the instrument technician. The less time trying to figure out what the drawings are saying, the more time can be spent on troubleshooting.
Documentation accessibility is a major concern. Documentation can't help if the technician can't find or understand it, or if it's wrong once he does find it. You'd think it would be a simple concept to maintain documentation, but if you've been in this business long enough, you've run across a system or two (or maybe a lot) where you can't find the manuals, or the drawings are incorrect or missing. In some companies, this is a costly way of life.
Good software documentation greatly improves its maintainability. System functional requirements, software functional descriptions, flow charts, software annotation, configurations, and I/O and memory mapping are some of the types of documentation that improve software maintainability. Up-to-date digital hardware configuration documentation (both hard and soft) on standard engineering documentation can also improve maintainability.
As-builts are a particularly abused form of documentation. They are many times not done or, if done, are not picked up by factory engineering, leaving future generations to suffer. Sometimes the engineering system makes it difficult to get as-builts picked up if purchase agreements don't allocate adequate money to get them done, or if the system is not organized and they just don't get done, to the detriment of all.