|In the mid 1980s we worked with a reference manual from a well-known Fortune 100 computer company. The manual, which explained how to use a text editor with a command-based user interface, gave us a great deal of grief. When we looked up a command in the index, sometimes the command was on the page that the index referred to and sometimes it wasn't.
Back then indexes were created manually. In the rush to get manuals out the door, index entries did not always get the quality control they deserved. Adding or deleting material at the last minute might make some index entries a few pages off.
With the manual in question, that knowledge did not help. If the command was not on the page listed in the index, then the command simply could not be found... until the next time we looked it up! The missing command might be exactly where the index said it was.
One day something even stranger happened. We looked up a command on page 5-117, but page 5-117 wasn't there. Chapter 5 ended at page 5-80!
Like most technical writers, we were busy. We didn't have time to confront the mysterious manual with disappearing content.
Finally, we got a major release out the door and had time to investigate. We started at the front of the manual and examined the organization. To our amazement, the manual had not one, not two, but three chapter 5s! Each chapter 5 documented a different set of commands.
The first chapter 5 ended on page 5-80, the second chapter 5 ended on page 5-42, and the third chapter 5 ended on page 5-120. No wonder we had trouble finding commands!
We've seen some truly bad technical writers in our time, but we've never seen one who would choose to include three chapter 5s in the same manual. The decision reeks of documentation by committee:
- Representative from department A: "We want to put the commands in three separate chapters."
- Representative from department B: "We want to put the commands in a single chapter."
- Meeting facilitator: "This meeting was scheduled to end four hours ago. Let's compromise: put the commands in three chapters but give all three chapters the same number."
Even with three chapter 5s, the index would have been correct and the commands would have been easy to find if the manual's pages had been numbered consecutively.