Jerry’s Silver Anniversary edition comments on documentation rang true when I recall an incident that came up during a review of the maintenance manual for a telecommunications operations support system. At the time, I was serving as VP of Engineering in a private company producing a business-critical billing teleprocessing system for telephone companies.
I was not always present for the review of every component of documentation, but there were a lot of programmers on the staff with no particular telecommunications systems experience, so I was very interested to see how the maintenance manual turned out. The system was conceived to operate continually throughout its decade or more of deployment, carrying all of the usage detail records for every phone call in all but one of the major telephone companies in the United States (as well as several in other countries), from which all of their usage-based billing revenues were derived. Obviously, routine maintenance and fault repair needed to be handled very carefully.
We were not 30 minutes into the presentation by the documentation team when a procedure was presented that started out: “First, power down both sides of the unit.” The unit in question was a central office-based real time teleprocessing node with 100% redundancy and fault tolerance designed into the hardware and, presumably, the software. I probably scared the meeting attendees half to death as my 6+ foot, 250+ pound frame nearly levitated with agitation. As I explained that the last time both sides of this system were ever intended to be powered down at the same time was the moment just before both sides were first powered up for the rest of their service life, I could tell from the look on the face of the programmers in the meeting (in addition to the look they had on their face when they entered the room due to even having to attend a documentation review) that there was a serious issue.
The senior programmer attending tried, as delicately as he could under the circumstances of my mood, to explain why this was the way to perform the procedure. I was calm enough to explain to him and the rest of those present that any design or implementation that compelled such a step in any procedure was flawed and they better go back to the drawing board and rethink their solution. Luckily, as it turned out, the changes in design and implementation of the software was able to adapt to the reality that had somehow escaped the programmer’s understanding. The hardware, which I had also influenced greatly during its design, was totally capable of supporting the proper approach.
I offer this example of the critical role documentation should play in the total packaging of a software-centered product.
In retrospect, I’d go so far as to say that today I’d take the approach of teaming systems designers and documentation specialists to co-produce the manuals before the detailed design. I’d make approval of the design and user documentation components a gating event for the commencement of detailed design and implementation.
I totally agree with you. Several years ago, I saw the disastrous results of what occurs when you do not team the systems designers, programmers, maintenance (operations) engineers, with the documentations specialists. Picture this:
ReplyDeleteWe end up with gear we were fortunate enough to power-up. However, when something broke we had no idea how to address the problem. We had no manual to tell you how the gear was supposed to function under various operating scenarios and how the code was supposed to be functioning as well. Worse still, when we tried to access the CPU to check the operating system we discovered someone forgot to install an access port. We had to open the box to gain access to the CPU; I then discovered my predecessor had no maintenance field experience because the access panel was on the bottom of the unit and it required a screwdriver that was not in the customer’s standard tool belt. This occurred. It became simpler to take a sledgehammer to the gear so that we could tell the customer the unit was beyond repair and had to be replaced. Knock on wood; it was a field trial.
I see documentation creation as a way of getting all of the parties that are a part of the creation, operation, maintenance, debugging, and repairing of the equipment/gear/system to speak to one another. Such discussion results in a better product.