原创 Incorrect documentation or none at all?

Recently, I had a modest troubleshooting assignment. I was involved in the mechanical repair of an interface box which had been removed from service, with four identical connectors hand-labeled as A, B, C and D, corresponding to internal channels. I was told that only channels A and B were live, and that C and D were disconnected internally.

After I did the repair, I went on-site and reconnected the cables—which were conveniently labeled as a, b, c, and d—to their respective connectors. "All done," or so I thought.

Well, not quite. The signals on cable "a" appeared at channel "B", while the signal of cable "b" didn't appear anywhere. It took a few minutes to realize the problem: those thoughtful labels A, B, C, and D on the box were wrong; I swapped things around, re-labeled the box's connectors correctly, and my work was done.

But the incident got me thinking. This was a relatively simple case of mislabeling and incorrect documentation. But in many cases, the situation is far more complex, and the requisite documentation more vital.

Yet often, we are given documentation which is incomplete or, perhaps worse, inaccurate. Then we spend our time trying to figure out which part of the documentation is correct and which is not, at the same time we are trying to debug the system itself. This documentation can be a system-level block diagram, a circuit schematic, or even a code listing.

The other scenario is to have minimal or no documentation at all. In that case, you have fewer misconceptions about the correctness of what you've got, so you can't be misled. That's the good news. But you do need to unravel the design with a blank sheet of paper in front of you, so to speak, and that can be very tough.

So here's the philosophical engineering question: is it better to have incorrect documentation which may help you get started, but which also may lead you astray; or to have no (or minimal) documentation which forces you to figure it out from scratch? What's been your experience? What's your preference?