I appreciate good documentation. I find the best documentation includes a good summary, followed by examples, illustrations, and then progressively more detailed information. If I recognize some transitive relationship with another concept, I don’t need a deep dive. I can probably glean the information from the examples and summary, which is why the detailed information should be after the examples and illustrations.

In the late 80’s, when we were still reading hard-copy books, I found that Brady technical books, especially ‘The Brady book of Turbo Pascal’ by Mike Edelhart, were very good. Mostly, because they would follow a convention where topic details, highlights, examples, and figures were laid out consistently from page to page. By the end of the book I was able to get most of the information from the examples and highlights.  This is still good practice for our electronic documents today.

I’ve always called IBM documentation a ‘race to knowledge’ (and not in a good way). What I mean is, IBM documentation usually contained a summary and a reference to another document that, in turn, provided a summary and a reference to another document. And so on, until you were back to the original document.  A few laps around the track and you begin to gain comprehension and can begin experimenting.

Today, many web sites follow this type of documentation flow where short summaries and links fail to bring the major concepts to light. The content pointed to by the link becomes an abstract of the whole and tends to lose it’s effectiveness in conveying the information desired/needed.  If you want an example of this pattern, look at the materials on the OASIS site.

Documentation is not a substitute

Most complex problems need documentation before a solid solution can be implemented. However, too often, documentation is where the software vendor ends it’s delivery experience to the consumer.  For example, take software installs.

During the early days of local area networks, vendors like IBM and Novell dominated the LAN market. The installs, much to their credit, included detailed instructions defining the configuration steps required to get the network stack up and running.  Once the install was complete, you had all the information required to complete the process.  Meanwhile, Microsoft was trying to make in-roads to becoming the network of choice.  While there was documentation, it was not generally needed, as the configuration would be complete at the end of the install.

I remember, the experience was less than optimal when installing a network stack on OS/2. Installing the software was easy enough and even created a template configuration file. But it required reading the manual, editing the configuration file, and ensuring that the different drivers where loaded in the proper order. And, heaven forbid, you had an improper semi-colon, misspelled keyword, or load sequence.  And if you need to reinstall – make a backup of your config – because a re-install generally broke the existing configuration and required you start all over.

My Microsoft experience, however (I know, fanboy), required only that I know the information about our environment and enter it during the install.  The details of the layout, formatting, keywords, and loading sequences inside the config file were eliminated as a concern. One reboot and the network was accessible.

This pattern of installing and immediately running the application is a hallmark of Microsoft software.  As i said, I’m a bit of a fan boy, but I lived the days of manual configuration and it was not pretty.  One missed keystroke, a typo, or dyslexia and you spent hours trying to find the error.  We are pretty much used to this install and ‘Run Now’ process but it has not always been the case.  I believe it is the main reason Windows won the client wars in the last and early part of this century.  And it won the server wars in the last century as well: OS/2 / Novell Netware – anyone  – ever heard of them?

Beginning with the start of this century, Linux has become the larger part of the network server market.  This is mostly due to it’s smaller footprint and lighter hardware requirements.  But give credit to companies like Red Hat for adding the install and run process to their suites. This drives down the total cost of ownership that enables the web application platforms to compete and take advantage of the internet era.

These are good examples and experiences of third-party software documentation practices, but let me know your ideas on the subject.

In a subsequent blog I will dive into documentation practices that we should embrace and avoid in our vertical software development.