CTO Articles
Published in IT World
E-Business in the Enterprise – August 23, 2005
Documentation - reporting and authoring are two different activities
By Sean Mc Grath
There are two documents sitting on my desk at the moment. One is 120 pages of documentation about system X. It is beautifully presented, table of contents, index at the back, one page per topic. Different font sizes and weights to differentiate pieces of information. The other is 5 pages of documentation about system Y. The presentation is pedestrian. The spelling and grammar eclectic.
Systems X and Y are on a par in terms of their complexity. I made one quick tour of the documentation for System X and binned it. I read every single line of the documentation for system Y - twice.
What gives? The binned documentation was generated automatically from a data structure in System X. It did not tell me anything that I could not have determined just as easily by looking at the data structure itself. Moreover, looking at the data structure directly removes the non-zero probability that the data structure is out of synch with the generated documentation. The document went to the bin because I could tell immediately that it was automatically generated from the data structure. In a sense, it was not documentation at all. It was simply a 'report' in the sense that an SQL statement gives you back a report. The raw data, pretty printed and served up with tops and tails to make a document.
The documentation for system Y on the other hand, was the work of a master craftsman. A craftsman whose craft is software engineering. In the space of 5 information packed pages he succeeded in telling me the things I really needed to know about System Y. The things that no amount of looking at the data structures or the code itself would tell me. In short, it was real documentation. Real words put together by a real person adding real value over and above what any 'report' would tell me. It was an authored document, not a generated one. That made all the difference.
Care is needed in refining the distinction of course. It is entirely possible and sensible to use automated mechanisms for gathering up real authored documentation to facilitate serving it up to a human being. JavaDoc [1] does this, so too does Doxygen[2]. So too does Knuth's classic WEB system[3]. The important question to ask yourself is this: does the documentation contain within it, significant amount of human-generated insight or is it a purely mechanical representation of a program or a data structure or a business process? The tools I mentioned earlier all provide mechanisms whereby hand-created documentation lives side by side with the computer notations and both are synthesized to produce the final documentation.
So, when confronted by an inch of paper in a new document about a new computer system, mentally subtract the number of pages that are generated mechanically from information that exists to keep the computer happy rather than information designed to keep a human reader happy. The higher the density of the former, the more expeditiously you might want to aim it at the bin. It may have been created more to be weighted than to be read.
[1] http://java.sun.com/j2se/javadoc/
[2] http://www.stack.nl/~dimitri/doxygen/
[3] http://www.csit.fsu.edu/~mimi/tex/doc/html/web2c/web2c_8.html