Virtuous pain of documentation

Francis Hwang's thoughtful post about the work and value of writing software documentation deserves careful reading. As Francis points out, writing a description of how to use software can go a long way to clarifying and improving the design and implementation. It's often said that the best way to understand something is to explain it to someone else. And trying to describe a programming problem or idea often yields the insight and a solution. This is a common experience of programmers, and is not limited to those following agile pairing practices.

Francis also discovers that as much as we'd like to believe that code can be self-describing, there are limits to this. Writing clear and understandable code is a prerequisite for ease of maintenance and development. But code is always a participant in a larger system; viz., the human world of use. This context cannot be described by the code. This is exactly the point made by Orcmid here and commented on here.

This, of course, opens a discussion about what exactly makes documentation valuable, usable, and maintainable.

Architecture, development, and use require a picture, model, or description of exactly how the software fits into the larger context of work. Work is a system; what's the program's role? Peter Naur's essay "Programming as Theory Building" explores this more fully. Maybe this fits with the agile idea of metaphor? One way I know that I have the right level of description is that it doesn't need updating every time the software changes. These descriptions are good for building system level acceptance tests; they describe the software behavior in the context of the user's work.

What about the code? I still work on this one, but I'm reminded of my early programming training on the IBM System 360/370. Those systems came with programming language manuals, but they also had a "Principles of Operation" that explained the system architecture, and how that was expressed and used in software instructions. It's true that in assembly language programs the hardware (and firmware) is visible, so understanding the hardware architecture was a big help. But I wonder if there isn't a place for principles of operation documents that help programmers understand the structure of an API, the class design choices, the rationale for function and method syntax. A description of what general design and implementation ideas are realized by the software could help a new programmer read the code and put it to use.

Francis has piqued my interest. I need to check out Lafcadio.

Technorati Tags: , , ,