We are told throughout our educations and careers that writing documentation about our software for other programmers, software documentation, is critically important. Though virtually every software engineer pays lip service to its importance, many fail to create proper documentation for their projects due to lack of interest, lack of time, or lack of direction. Documentation is as important as design, implementation, and testing in constructing quality software, however, and inadequately documented software is poor software. It therefore follows that groups producing poorly documented software are fundamentally flawed. Establishing a documentation standard and a documentation creation and publishing pipeline is part of setting a group’s technical direction. The standard ensures that the developers prioritize creating documentation and the pipeline ensures that excellent documentation is generated as efficiently and painlessly as possible, which in turn positively reinforces the group’s documentation standard.

The first kind of software documentation that a standard should mandate is code documentation, or comments in source code. There are two kinds of code comments:

1. Comments discussing the intention of a piece of code, where this is not obvious from the code itself
2. Comments describing an interface (class, function, or method), particularly its inputs and outputs

I write such comments after finishing a module, while reviewing the code, because I have found that comments written while a module is being developed need to be revised constantly during the development, wasting time. Aside from just creating documentation, this process actually improves the code itself. Writing the first kind of comment forces re-examination of tricky code and often leads to simplification and clarification of such code. Writing the second kind of comment forces rethinking of interfaces, in particular whether an interface really is necessary, desirable, and well-expressed; I frequently remove methods, alter argument lists, or change names while documenting code. In addition, documenting an interface’s inputs often reveals potential error conditions. Both types of commenting greatly increase the speed at which other programmers can understand and modify code and so directly contribute to a group’s efficiency, repaying the original time investment to write the comments. Interface documentation is particularly important in this regard, because it often can prevent the interface from being invoked incorrectly, saving debugging time. Comments also make it much easier to maintain code without the original author being present, which is crucial given that people change jobs very frequently (US citizens change jobs roughly once every two years) and that open source code may be used and modified by programmers from all around the world.

The second kind of software documentation that a standard should mandate is package and library level documentation. README files distributed with packages and websites describing libraries are this kind of documentation (this README is a concrete example for an open-source package that I maintain). While code documentation should be exhaustively complete and can discuss low-level details, package documentation only should discuss important, high-level concepts. It should not duplicate code documentation. Each method in a class should be commented, for instance, but package documentation discussing the class should review just the class’ main features and the methods that need to be called in the class’ most common use cases. In fact, package documentation should be organized around a series of examples that both illustrate what the package can do and quickly teach the reader its basic functionality. Such examples make the package easier to use, since the reader may not need to look at the source code for common use cases, and also serve as excellent advertisement for the package’s features, making it more likely that the package will be used. This is especially important for open-source software, as excellent package-level documentation distinguishes such software from the competition and also can be indexed by search engines.

Good programmers always will create documentation, even in the absence of any support. One group that I worked in had no documentation standard, for instance, and some developers still documented their work. There are a couple of problems with such a group’s documentation, however. Firstly, without a documentation standard, different developers inevitably will document differently and to different degrees. While inconsistent documentation is better than no documentation, it does hinder the creation and use of a documentation repository. Time will be lost as developers are forced to switch between documentation styles throughout the day. Secondly, some developers inevitably will create insufficient documentation, dragging down the group’s efforts and creating an environment in which poorly documented software is acceptable (the broken windows effect). Parts of the system will not be documented at all, emasculating a documentation repository as developers will not be able to trust that it always has the information that they need. In my prior group, for instance, many developers never bothered to use the doxygen repository because it was incomplete and instead always went directly to the source code.

In order to establish a documentation standard, a group’s management must classify software documentation as a mandatory deliverable for every project, and project planners always need to budget time for it. Management also must instruct developers and team leaders to enforce the standard during code reviews and should evaluate programmers partially on the basis of the documentation that they produce. The group’s technical leadership, moreover, should outline requirements, evaluate and purchase products, and ask developers to write tools for an efficient documentation creation and publishing pipeline for the standard. This will ensure that the group gets the greatest bang for the buck from creating documentation. Also, as even good programmers often do not enjoy writing documentation (viewing it as a necessary evil), an excellent pipeline is a carrot that helps to ensure acceptance of and compliance with the documentation standard. I will discuss what constitutes a good pipeline in my next article.