The heart of a documentation pipeline is a tool or series of tools that read software documentation and generate formatted documents; these tools are called documentation generators. Such a tool might process a Ruby source file containing a class and generate a web page listing all of the class’ methods and displaying each method’s comments. Different documentation generation tools support different languages; in general, the more popular a language, the more tools will be available for it. Some tools, such as Doxygen, support a number of programming languages while others, such as RDoc, focus on only a single language, Ruby in this case. If a tool focuses on only one language, it likely will provide much better support for that language than does a more general tool. RDoc, for instance, is the only tool that supports Ruby’s metaprogramming constructs. When a group works with several languages, using the optimal tool for each language must be weighed carefully against using one tool for multiple languages. This is a very nuanced decision that should be made separately for each language and that depends on how tightly coupled the language’s code is with that of the other languages, how long it will take for the developers to master the language’s optimal tool, and how much benefit the language’s optimal tool offers over a multi-language tool. If a group maintains a code base that has different languages calling into each other, then I recommend using a single tool that can handle all of these languages and that preferably can understand the relationships across the language boundaries. At a prior employer I worked in a group that maintained a system written in C, C++, Fortran 77, and Fortran 95, and a documentation tool that could have understood the inter-language relationships would have been very valuable. RDoc, for example, provides this functionality for C and Ruby; although its purpose is to document Ruby code, it can parse C and understands the C/Ruby calling conventions, allowing it to document properly libraries consisting of both C and Ruby, which are common.

Aside from generating documents from code and comments, most widely-used documentation generation tools also define a markup language that can describe elements of the software documentation. A key characteristic of such a markup language is its expressiveness, particularly whether the markup can describe all program elements properly. Beyond being able to describe common elements like lists, headings, and emphasis, the markup also should be able to describe code constructs like method parameters, return values, and possible exceptions. While markup is not needed to generate basic documents, it greatly increases the expressiveness of the documentation and enhances the information conveyed by the generated documents. Describing elements with markup allows document formatting to be tweaked to display the elements in special ways, such using a particular color for method parameters. Without expressive markup, developers often use primitive markup in order to format documentation properly. RDoc, for instance, does not offer markup for parameters and return values, and so my company simulates such markup by using the less descriptive markup for headings and lists. Not only is the required markup longer, more painful to write, and duplicated throughout our code base, RDoc does not understand the elements properly and so cannot generate optimal documents with them.

Another important characteristic of a documentation generation tool’s markup language is how easily it can be understood, modified, and written. XML and HTML, for instance, are very verbose (since each tag must be closed), and I find that the tags obscure the content. Such complicated languages also are difficult to write correctly and so are painful for developers to use to write comments. By contrast, there are a variety of markdown languages that are easier to read and write (wikis often use markdown languages for this reason). It is vital that marked up comments be legible as text, since programmers working directly with the source code must be able to read them. This also is an important consideration if the package-level documentation is distributed as text files (for example, RDoc transforms a README that I maintain into beautiful HTML, but the text file remains very easy to read).

A defining characteristic of a documentation generation tool is the format of the documents that it generates. At a minimum, it should be able to generate web pages, since web pages can be viewed on virtually every platform, provide a plethora of stylistic options, make cross-references very easy to follow (via links), and can be searched easily. Additionally, if the web pages are published on the public internet, they will be indexed by search engines and so will advertise the software. Finally, web pages easily can be proofread by developers before releasing documentation. It is crucial that the default look of the web pages be as aesthetically pleasing and as readable as possible, so that the documents will be a pleasure to read. The look also should be customizable, so that the group’s developers can tweak it, and so that developers around the world can craft better looks. In addition to being more usable, appealing web pages are strong positive reinforcement for developers writing documentation. The tool also should generate cross-reference links to the appropriate documents for class names, method names, modules, and other source code entities, as such links make documentation much easier to use. The tool additionally should be able to link methods to syntax-highlighted source code, allowing readers to browse the source easily in the context of the documentation. Finally, the tool should be able to generate and embed class diagrams. Javadoc, Doxygen, and RDoc are examples of tools that offer all of these features.

Depending on the readers of a group’s software documentation, it may be desirable to publish documentation in other formats besides web pages. Some UNIX programmers, for instance, prefer to read software documentation on the command-line, and so tools exist for this such as man for UNIX utilities, perldoc for Perl scripts and libraries, pydoc for Python libraries, and ri for Ruby libraries. Windows programmers, on the other hand, often read software documentation in Windows Help, and so many tools can generate documents in this format. In order to make the documentation as usable as possible, the pipeline should generate all applicable output formats from a single documentation source, either with one tool or a series of tools. Javadoc, Doxygen, and RDoc all can generate documents in multiple formats.

After generating documents, a pipeline must publish them to at least one repository in order to allow developers to view them. The nature of this repository will, of course, depend on the document format. At a minimum, however, it should allow developers to search the documents. In addition, it should be accessible from wherever the developers will work; if developers log into a corporate system from home and code, for instance, then they also should be able to access the documentation repository from home. Depending on the software’s release cycle, the repository may need to store multiple versions of documentation, tracking different versions of the software. Lastly, it must be kept up to date, so that developers always can trust that it reflects the code base faithfully. This should be automated in order to eliminate human error and in order to save developers yet another chore when moving code. A prior employer ran a scheduled job that generated documentation nightly from the production code. At Designing Patterns, our build system generates and publishes documentation when releasing new versions of our open-source packages.

While it may take some work to establish, a good documentation pipeline will justify the effort by increasing programmer productivity and happiness, positively reinforcing the 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.

Software is an abstraction of the operation of very complicated machines, and so programming, more than most other disciplines, demands that its practitioners think abstractly, which in turn requires recognizing and thinking in patterns.  One excellent example of this is learning new programming languages.  One’s first programming language always is the hardest to learn.  During this process, one’s mind does not have a store of patterns with which to interpret the new language, with which to understand and differentiate programming concepts and language concepts.  Instead, programming initially is a series of magical formulas, which, given proper application and the right phase of the moon, produce the right output.  For example, when learning C, pointers often are introduced simply as syntax allowing a function to modify its arguments.  Such formulas are not properly patterns at all, since they cannot be applied outside of their native context.  As one executes work with the language and begins to understand some theory, however, one starts to generalize the magical formulas into patterns and, armed with these, develops the ability to work and thrive in new contexts with the language.  Understanding the relationship between pointers and pointees in C (indirection), for instance, allows one to work competently with C’s memory allocation facilities and to do things like construct a binary search tree.  Learning a second language accelerates this process because understanding the patterns underlying it allows one to factor out common patterns in the two languages, which likely have far more general application.  An understanding of C’s pointers might become an understanding of value and reference semantics after learning Java, for example.  Applying the patterns of one language to learning another also helps one learn the new language much more quickly than one would have otherwise, as the new language’s patterns are highlighted by the old language’s patterns.  I learned Ruby several weeks ago, and I found it very useful to compare every new aspect of Ruby with C++, even though Ruby and C++ are very, very different languages.  Understanding C++ helped me to understand the concepts underlying Ruby programming.  My learning process can be seen in this Wiki page, which I updated with my observations while studying the language; it consistently compares and contrasts Ruby with C++.

Most programmers probably would agree with the above assertion, that recognizing and formalizing patterns is the key to software engineering, and that failure usually is a result of not grasping a particular pattern.  Many, however, use patterns passively; that is, they apply them in the contexts in which they were taught to but do not generalize them to new contexts or formalize new patterns.  That is, they see patterns as little more than magical formulas.  They equally happily put common code into functions in order to avoid duplication and create build systems that rely on duplication simply because they were told to do so, never stopping to judge and classify each pattern.  They apply canned design patterns in specific situations, but do not really understand that the underlying principles that make a particular pattern advantageous (looser class coupling, for instance) must be embodied by patterns in other contexts as well.  These failures of understanding, while apparent in whatever work a programmer produces, become painfully obvious in a large software system where a programmer must apply patterns embodying good principles at multiple abstraction levels in order to be successful.  Cyclical dependencies, for instance, do not cause much damage in a small system but, when the patterns applied to a large software system result in cyclical link dependencies among dozens of libraries or cyclical operational dependencies among dozens of machines, they create a maintenance nightmare.

Whatever one is doing, whether learning a language, implementing a module, designing a class hierarchy, creating configuration files, drafting requirement specifications, or architecting a system, one constantly must step back and assess one’s work in order to discern the patterns that underlie the work.  After recognizing and formalizing the patterns, judge them according to good design principles.  When others offer criticism of one’s work, assess the criticism in light of its patterns, and if necessary, change the work and your understanding of its patterns at the same time.  When one notices a problem in a system, do not simply correct the problem but instead probe into what allowed it to exist in the first place.  When someone asks for help, do not simply answer their question but instead try to explain the pattern underlying the answer and the principles that you use to judge the pattern.  When working on something that feels wrong, seek to understand what aspects of the project violate beneficial patterns or manifest negative patterns.

I am passionate about programming, and I want to improve.  I have no doubts that continually formalizing and applying patterns will make me a stronger programmer.  This blog, by forcing me to commit patterns to virtual paper, will help me do to so.  Hopefully, others will learn from my experience.  In addition, as I have benefited greatly from learning from others, I also want this blog to stimulate discussion, so that the understanding of others will improve my own.