Helping Users

There are two broad categories of documentation which exist and are or can be maintained outside the code. 

         These can broadly be defined as User Help/Specifications and Design/Architectural Descriptions. This blog posting is about User Help/Specifications.  Originally the two were intended to be in the same posting but because of size and some work I want to do for the Design/Architectural posting, they have been broken up.

          This type of documentation is primarily intended to be read and used by end users. It most commonly takes the form of ‘Help’ information presented at run time. The 'Specification' part most often takes the form of manuals but that is not a topic for this blog.  The distinction between run time help and manuals is sometimes blurred.  A simple example of this type of blurring is when a description of the format of an input/output file is needed.  

          The first question I ask is "does the user need to know this before the program starts?".  If the answer is yes then a manual is needed.  The second question is "does the information take more than half a screen height to display?".  If the answer is yes then a manual may be needed or a more complex display system such as a web page is needed.

          This topic is part of maintainable software because it is often part of a maintainer’s job to keep it accurate and it also serves as a reminder of what the application software is supposed to be doing and not doing. The run time 'Help' information is typically the most volatile aspect of maintaining software.  But if implemented with some forethought it can be done without requiring code changes thus avoiding the overhead of a formal release.

          The display of help information is usually triggered via a command line option which causes the program to display the information or switches control to a web page which presents the information.

In cases where there is no such command line option the program may display a line with the program name its version id(number) and possibly a statement of what the program is supposed to do.

          The choices of where to put this type of information are simple, build it into the software or put it in files outside the program.  Building it inside the software works quite well for script languages such as Perl but not so much for compiled languages such as C or C++ .  If the information must be available for web or manual publication then the only practical choice is to put it into file(s).

          One of the most successful methods I have used to minimize the maintenance effort is to put the information in topic specific files then use Doxigen to format and organize the files for program and web use. This means that there is only one copy of the text to maintain and that the code is not affected by changes to the content.  This is an example of the WORM (Write Once Read Many) principle, which basically says that a piece of information should only be stored in one place no matter how many references to it exist.

          The above pattern can be implemented by a simple encapsulation function which allows the calling code request the display of a specific topic (string) and that the only thing the calling code may need to know is if the display was done properly or not (return value) (e.g. the information was available and displayed). 

          Maintainability can be enhanced by having the encapsulating routine translate the topic name (as supplied by a user) converted to a file name by simply adding a suffix and/or perhaps prefixing the program name. This mechanism allows the addition of help topics by only changing the help files. This assumes that the command line description is also contained in a file.  A variation on this is to place the topic name in a URL which is then sent to a browser for display and handling.

          A related aspect of maintaining information a user might want to know is maintaining a programs version id/number.  At one point in my career I designed and implemented a subversion based system which among other things automated the checkout, testing and release of numerous programs.  A part of this was a mechanism to automate the update of version ids for these programs (independent of the implementing language of the program) and support for all types of external documentation.  The premise was that if it is easy to do the right thing (including maintaining documentation) then maintainer’s even engineers in a hurry would do it.  This has proved to be true, even years later.

          In my opinion, one of the best examples of a good command based help system coupled with a manual is the one implemented by subversion red book (http://svnbook.red-bean.com/en/1.7/svn-book.pdf) and the svn command.  I have used this as a model for several applications.  I have also designed/implemented applications which used web pages to present the help information.  All of these applications were designed with the goal of not having to make code changes just to update the help information.