The Other Face is the 15th installment of the Re-Read Saturday of the The Mythical Man-Month by Fred P. Brooks. In this essay Brooks tackles the thorny issue of documentation. Both code and documentation are the manifestations of a message. Code is the tool though which the programmer communicates with the machine. Documentation is the tool through which the programmer communicates with world outside the operating systems. Both communication paths are critical to delivering the most value possible. While documentation is widely acknowledged as need, the downside is that, from time immemorial, documentation has been viewed as a scourge, a pain, and sometimes as a punishment; it is designed to keep developers from doing real work – creating code. Leaders and teachers need to find a means to surmount this seemingly natural hesitancy. Brooks’ solution is to show them how to do the documentation needed, rather than relying solely on exhortation.
Brooks begins by laying out the three different levels of documentation, and the requirements each conveys.
- Documentation needed to use a program. The prose description of the program forms the centerpiece of the documentation needed to use a program. Brooks includes nine categories of information, ranging from purpose to operating instructions, in his definition of the program’s description. The idea is to start the description at a high-level, and then deconstruct the data into a more detailed view. In many organizations I have observed that some organizations use technical writers to shift the burden from the development teams for this level of documentation.
- Documentation needed to believe a program. Simply put, this documentation includes test cases need to prove the program works. Including the test cases to prove the program actually works in a repeatable manner is the basis for Agile testing. Again, Brooks foreshadowed the ideas that would evolve into the technical components of Agile.
- Documentation needed to modify a program. Having worked as a maintenance programmer more than once in my career, I have more than once cursed the programmers that came before me as I tried to understand the convoluted code they had written. Brooks identifies the typical documentation organizations need to change or adapt a program into five basic categories:
- Flowcharts (Brooks argues later in the essay that flowcharts are oversold),
- complete descriptions of algorithms used,
- description of file layouts,
- overview of the pass structure, and
- a discussion of modifications contemplated in the original design.
The focus of this type of documentation is single-mindedly on what will be required when someone is making a change or contemplating making a change to a piece of code.
The solution Brooks suggests is relying less on the obsolete nuisance of flow charts which he believes are only suitable for initiating beginners into algorithmic thinking, and instead leveraging self-documenting programs. Self-documenting programs disprove the fallacy of the need to maintain code and documentation synchronously. In agile it is often said that code is the only documentation programmers need for support, although some more mature Agile teams combine code and test as documentation. For programs to be consistently self-documented requires building the process directly into how work is completed while reducing the burden placed on the developers. Good self-documented programs use all of the bells and whistles built into the language being used, leverage white space and formatting to enhance readability and also include comments.
Brooks culminates the essay with the sentence “since machines are made for people, not people for machines, their use makes every form of sense, economic in human.” The point is that since the interaction between the developers represented a flow of information there is no reason we can’t reuse the same information as program level documentation.
Previous installments of the Re-read of The Mythical Man-Month