Document Nonexistent Systems

DocumentationPatterns AntiPattern.

Some people think that, before they start coding something brave and new, they have to:

I have no idea why people do this.

Or do I? When introduced to some new system, most people (me included) read:

before they actually install it and give it a test drive. But this doesn't mean that the system was written in that order. Here are some things that were implemented before their documentation was completed (and that documentation): Here are some things that were documented before they were implemented:

To DocumentNonexistentSystems is a mistake. Build a little system. Try it out. Tinker. Use trial-and-error. But START! DO SOMETHING!

--MattRickard

This doesn't quite explain the people who refuse to read documentation before diving into a new system but whose first instinct is to produce it when they start to create a new system. I count myself in this category. A better explanation is that people are trying to create a mental model of the system they are using or building and that actually using the system is the fastest (or even the only) way to construct such a model but that getting caught in coding details hampers the mental modeling of a non-existent system. -- RichardKulisz


My scyscraper fell down when i just did it. People got mad that i wasted their time.


I've written collapsible skyscrapers too! But isn't it less painful if you just show the powers that be, your collapsible skyscraper, instead of an executive summary of a feasibility study of a proposal of a public hearing of ...

Oh and solid coding does hamper the mental model. But maybe just document and diagram it for yourself now, and for everyone else's benefit later.

--MattRickard
''It took 4 years and several hundred million dollars to make it collapse so well, so no, it wasn't less painful.''
1. Industry analogies strike again. I'm not in the building industry. I write software, and to build software, I don't use lot of manpower and machinery and time, but instead use a compiler.

(Oh, mass production? Software can be mass-produced too, but it's much easier to tool up a CD recording plant than most other factories - just send them a CD-R.)

Since the building (and mass-production) steps are so straightforward, if it's not quite right at any stage during design or delivery, refactor that software.

Bill Gates made himself "Chief Software Architect" at Microsoft for no particularly good reason.

2. It is a lot harder to test a document than it is to test a program. (Hint: try running a document.)

--MattRickard


It may be easier to run a program than it is to run a document, but running is only half of testing. On the other hand, it may be much harder to run an incomplete program than to review an incomplete document (or program).

When you read a document, you're "running" the document, but you're not running what it describes. A subtle distinction.

As for the other half of testing, when you run a program, how do you know if it passed? Give an example if you can.Think

-- WaldenMathews
CategoryDocumentation

EditText of this page (last edited February 21, 2003) or FindPage with title or text search