[Framers] What causes documentation to fail

[Steve Rickaby]

Has anyone mentioned structure in this discussion? I don't mean structured vs. unstructured, I mean documentation design. Documentation can be basically sound, but rendered unusable by poor information design and/or lack of suitable navigation tools.

This problem becomes geometrically worse as documentation sets grow, especially for complex systems with many interacting components. Many years ago I worked with Hewlett Packard minicomputers (the HP1000 series, if anyone remembers those). These machines were ferociously good for their time, but the documentation was pretty dire. As the capability of the machines had grown, the documentation set had grown alongside them by merely adding new manuals, much as Nature evolved the human brain by adding new bits on top of old bits ;-)

There was no global view, so solving a technical issue often involved picking through multiple, thick, manuals that deal with older, newer, higher and lower levels of detail. I often found myself five or six deep in open manuals at the end of a happy day of debugging. I am sure this was very good for my mental training, but it was not an efficient way to work. I doubt if this was an isolated problem. 

I would be a lot richer now if I'd applied the same level of concentration to Unix systems, but sadly I merely became expert in an operating system that was soon to become obsolete. But the memory lingers: great hardware, awesome operating system, ghastly documentation.

-- 
Steve