"Documentation is the castor oil of programming. The managers know it must be good because programmers hate it so much" (p.262)"

– From 'The Psychology of Computer Programming', Gerald M. Weinberg 1971

It would be a great pleasure to point to a golden age where it was a standard practice to create the user documentation before the application. It is a pleasure I must forego because, unfortunately, it was always an unusual, though excellent, practice. The natural inclination of any developer has always been to shy away from documentation like the devil from holy water. Instead, we maintain the foolish myth that the source code 'is its own documentation', or that it is pointless to produce it because nobody would read it: a wild theory that I've never seen put to the test, though it is true that few developers even read their own code, let alone any documentation. However, it could be that with Agile's idea of user stories, use cases and usage scenarios, we are stumbling towards the realization that this is a most effective way of creating applications and one that almost guarantees success.

I discovered how effective the "document before you code" technique was in the late seventies, while running a programming house that created commercial applications for local businesses. We did fixed-price contracts, so if we got the estimation wrong, we didn't eat. It concentrated our minds towards getting our time and cost estimates right.

We hit on this method: first, we wrote the user-documentation, which we used to gain the contract and estimate the development effort. Then, the developers created the application to fit the documentation. As well as the operator's manual, we created a maintenance manual that specified all the support tasks and interfaces. It worked fine, though it was far less exciting than the instinctive method of making one's mind a blank and wandering towards the keyboard to write something vaguely splendid.

Nowadays, one cannot write user documentation the way that old-timers like I did it, since the user-interfaces are now too complicated to permit mere text description. No. Nowadays, the way to design an application is to write the user documentation along with mock-ups of the screen, describing all the user processes, workflows, and alternative navigation paths through the system. If you get aspects wrong, you delete the offending part and redo it until it is right. It isn't a substitute for getting the architecture of the application right; it forces you to get the architecture right, even if it isn't made explicit.

There are unexpected benefits from writing documentation for an application that doesn't yet exist:

• Mistakes in the user interface stick out like a sore thumb.
• The users tend to understand it easily, if done well, and can spot the mistakes easier than if you give them UML with fluffy clouds.
• It is much quicker and effective to alter it than to wait until you've started writing the application itself. A description of a form, or dialog box, is far easier to change than the actual thing created by computer code.
• The morale of the developers suddenly increases when they realize that they have avoided going anywhere near documentation.
• By doing the documentation, it becomes obvious if you have left vague any areas of the application, which are likely undo all your time and cost estimations.
• It forces us to learn the language and concepts of the business processes before designing the schema.

Let's face it, it is boring to do, but developers work best when singing from the same hymn sheet, and user documentation is the hymn sheet of application development.

Phil Factor