3. Software Documentation

3.1. Learning From What Works

Anyone that learned to use Lotus 1,2,3 back in the early days of personal computers, became keenly aware that even after Lotus Development Corporation had developed its excellent, powerful spreadsheet software (that efficiently lived on a 128KB floppy disk — yes, the .EXE file was about 120KB in size), the software could not have achieved its screaming success without a bridge that helped users to learn to use it, and achieve success using it on a continuing basis.

  • Easy to find and access:

    Back then, IBM required all IBM-PC software documentation to be in an easy-to-use hard-bound ring binder, which fit nicely on the short shelves of a desk, in which pages, sections and chapters could easily be replaced when they needed to be updated (e.g. when the software was updated).

  • Easy to discover if it would solve a specific problem:

    Its introductory material quickly oriented people who did not even know what a spreadsheet was, thus very quickly answering The Basic Questions, “What is it?” and “What does it do?”, and by extrapolation, “What problem(s) does it solve?”

  • Easy to learn:

    It contained excellent, clear, introductory material that walked a person through learning to use it, with “links” to the detailed reference material for when the reader was ready for it.

  • Easy to find answers to specific questions when they arose during day-to-day use:

    Its detailed topics were well organized with labeled section dividers, well written (clear and easy to understand), and complete. When one didn’t know what topic a question was under but knew a key word, it had a thorough and accurate multi-level index that made it very quick and easy to locate what you were looking for. And the detailed content on each topic was all in one place.

Another classic example with an extremely successful history is Unix man(ual) pages. On any Unix (and now Linux) system, its tools and their documentation were literally at the fingertips of Unix users. And all new software installed came with its documentation in man pages. One could quickly learn A) what tool to use, and B) how to use it (e.g. a command-line tools, shell commands, special system files, file formats, system-administration commands, and other things) merely by typing “man” plus the name of the thing one was looking for. And the documentation was usually really well organized. In almost every case, one can find the answer to the first two The Basic Questions, “What is it?” and “What does it do?” in the very first line of text the user sees, and in the worst case, in the first 15 lines of the first page of documentation. If you have a Unix or Linux system available (or a Cygwyn installation under Windows), try it and see what I mean. One of the very first things a Unix/Linux user is taught is: man man — how to use the man(ual) software itself! Man pages were typically organized with the following headings. In these headings you can see the progressively-increasing gradient of information, from broad and general basics to progressively more detail, roughly in the sequence the reader will need it.

  • NAME (name and answer to “What is it?”),

  • SYNOPSIS (a condensed statement or outline; for command-line tools, a syntax diagram),

  • DESCRIPTION (finished answering The Basic Questions about the tool, followed by details),

  • OPTIONS,

  • EXAMPLES,

  • EXIT STATUS (when applicable),

  • ERRORS (when applicable),

  • ENVIRONMENT (when applicable),

  • FILES (when applicable),

  • VERSIONS (when applicable),

  • NOTES (when applicable),

  • AUTHOR

  • REPORTING BUGS, and

  • SEE ALSO.

Keep in mind: these were hugely successful headings for a reason: they made readers successful with those tools in a minimum of time.

3.2. Learning From What Doesn’t Work

On the other side of that coin, Microsoft once had a great documentation program (circa 1992) when it had a thorough and well-written manual on the Windows Operating System (v3.1) that started with real basics: What is it? What does it do? How to install it. And best of all: features of the Windows user interface that applied to all software that ran under Windows. It explained that each rectangle or “thing” on the screen was regarded as a “window”, and had many things in common, and that the overall “window” was the primary interface of a software application. It covered title bars, application icons, menus, buttons, and various other types of controls, and how they behaved with both the mouse and keyboard. It did this because at that time, all Windows software was required to be written so that it remained useful even for systems that did not [yet] have a mouse.

Since Microsoft decided to stop printing manuals, over several decades, their documentation program steadily and progressively failed to deliver success to its users, while making it more and more difficult to find and/or understand. Most of the understanding failure was tied up in the mere failure to answer The Basic Questions “What is it?” and “What does it do?” early in the documentation for each tool. Just try to discover the answer to the question: “What is Azure?” (one of their huge products), and see how many minutes (or hours) it takes you — if you can find the answer at all before you give up!

I will say, however, there is hope on the horizon for Microsoft: Hitting the [F1] key in Visual Studio while the cursor is on specific keywords in source code often serves up (usually) decent documentation and fast. Though where that documentation fails, when it does, it is almost always in not answering The Basic Questions early in the documentation for that tool. Sometimes they are answered later, but if you can’t find the answers to those questions, what good is the rest of that documentation?

As covered above, these questions should be answered in the very first material that the user sees when trying to look something up, i.e. the top few lines of the “landing page” (when referring to HTML documentation) or whatever other form that documentation might be in.

TODO