26-Sep-2024 by Victor Wheeler

 

 

Before going very far with Code Documentation (another related article), let us first have a look at the parts of these best practices that apply to all documentation — any written material meant to teach.

 

 

 

The purpose of documentation is to enable the reader to achieve success with your product through gradiently-progressing understandings while simultaneously quickly answering specific questions the reader is asking.

 

I have found that the strategy and tactics used to successfully achieve that purpose are shared by all written documentation for a product — I assert:  for any kind of product.

 

I call them "Best Practices" because they are well known, successful methods for helping readers achieve that success.

 

 

 

Like any product one is learning to use or manage that is complex enough to require documentation — software or for that matter, anything in life — that product's success is strictly governed by the success it brings to its users, and how fast, and how easily that success is achieved.

 

 

 

The "how fast, and how easily" parts of the above principle is where documentation comes into play:  documentation provides a bridge for your reader, to carry him from knowing nothing about your product, to knowing enough about it to competently use it to overcome obstacles towards achieving his own goals.

 

 

 

To introduce this topic, I will first talk about software, though you will undoubtedly realize that this topic follows the same patterns of any human being learning to use a complex product to overcome barriers towards achieving a goal, and thereby achieving success with it.

 

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 126KB 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.  This required documentation that had these qualities:

 

 

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 question, "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, try it and see what I mean.  And one of the 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.

 

 

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

 

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.  Features of the Windows user interface that applied to all software that ran under Windows.  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 "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!  (Though I will say, 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 questions, "What is it?" and "What does it do?")  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.