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.

For many of us, we develop software that is meant for vertical markets such as banking, insurance, energy, retail, health care, lending, etc.  Unlike Facebook, Google, Microsoft, and Apple, our markets are smaller, but in many ways more demanding because we need to cater to a client base that has processes and systems that include legacy technology and are more entrenched.

I mention these heavy weight companies because they are successful and provide many of the resources, tools, software stacks, and hardware that we rely upon. Not to mention, they also provide products and service we need to support.  We can learn a lot from these guys and should take advantage of all their resources. But our software requirements are different, our users are different, and we have a lot more interaction with legacy systems, processes, and data.

Not to downplay the excellence that is Facebook, the internet while mature is relatively young; especially compared to the industries we support. Implementing a revelation such as Facebook, from a software standpoint, is much easier than the software you create and maintain on a daily basis.  We can learn a lot from Facebook (and others), around performance, scaling, deployment, versioning, and upgrading. Their sheer volumes alone are enormous and it is rare that anyone complains about response times or service. I know I can usually blame my ISP for any outage or performance issues.

Our industries have processes and systems that have been in place for decades. And they drive very important aspects of a company’s business or municipality’s services. Not all processes are automated. Many are manual and have paradigms that are not easily translated into software solutions (or they would have been so already). Happy paths are easily explained and usually the first aspects translated to software.  But the exception paths are many, not easily identified, and are obfuscated by the many transitions from exception back to happy path.

The transitions can go through many hands, from one department to another, can involve research, confirmation, and in some cases authorization. While happy path constitutes 90% of business as usual, it is the 10% that costs our industries the most.  From a widgets counting standpoint, 90% sounds really good (and be sure it is) but it does not address the major costs and pain points which our clients really want and need us to address.

Integrations are a major concern for our software. It is critical if you want to compete for new accounts. It is not likely your software can replace all the systems used by a client. Your ability to integrate with their existing systems can make the difference for your sales team. You don’t necessarily have to include the integrations out of the box, but you must have extensibility built-in to reduce the implementation time line and costs. Being able to show a simple integration, like importing a spreadsheet, during a demo has been very effective in the past. Especially if you can illustrate the same capability as an automated process.

This is where I want to focus my blog. Developing software for vertical markets and legacy industries is were a lot of us live. I hope you find this useful or helpful and will participate by providing your ideas, criticisms, and insights.

Please register and let me know what you think.