Our enthusiastic adoption of advanced development tools and frameworks has diverted us from the hard work of delivering effective system documentation.
A few weeks ago I wrote about an experiment to see what a system would be like if we focused solely on functionality and manageability, rather than on technological elegance. I have been slowly carrying out the experiment, building a system which is well documented and manageable, but uses only very simple programming with no advanced tools or frameworks.
So far in the project I have drafted a set of documents for the system: user documentation, support documentation, operations documentation and legal documentation such as licensing. I have created mock-ups of most of the screens for the system, as part of the user guide.
I have found it really hard to think through and write down how the system is maintained, installed, operated and used. This is nothing to do with the lack of development tools or frameworks, because I have not started development yet.
The documentation describes what the screens looks like, the business rules, and how the technical components work and are configured. It is reminiscent of the system specification documents from a typical waterfall method. Am I recreating a bureaucratic and out-dated development method?
I do not think so. I am writing detailed documentation as part of the deliverable, not as part of a design method. The documents I have created explain how to use and work with the system, not how to build it. When I worked with waterfall methods, the huge documents were focused on getting sign off, and were typically ignored at the end of the project.
The documentation I have created seems to me to be a useful part of the overall solution. I have been trying to think why so few systems are documented like this. I have a hypothesis.
Years ago, computers were very expensive and hard to use. Programs were written out by hand and desk-checked before being compiled. We wrote in COBOL and assembler. Go back far enough and we were using punched cards. We produced lots of documentation so that we could get it right first time when we started programming on expensive and inflexible technology.
We now have cheap hardware, integrated development environments and advanced frameworks. This allows us to adopt much more efficient, iterative methods. We do not have to get it right first time, so we do not need so much design documentation.
However, in making this change, we have forgotten that old-fashioned, cumbersome design methods created system documentation as a by-product, even though it was often ignored. It is as if we have dismissed the whole notion of documentation because of its association with inefficient old ways of working.
If we think of documentation as part of the deliverable, rather than part of the process, then there is less conflict between documentation and more modern, iterative, agile methods. We can create the detailed system documentation required for usable and manageable systems, but we can create this iteratively, in parallel with the creation of the code.
Maybe our advanced technology, methods and tools have given us a bad excuse to avoid the hard work of creating good system documentation.