Document Nonexistent Systems

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

write a management proposal
write a functional specification
write a technical specification
draw up the interfaces in RationalRose

I have no idea why people do this.

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

An abstract, or executive summary
An overview of what it supposes to do
A summary of how it does it
Two or three diagrams, each reminiscent of a flowchart

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):

C (The C Programming Language)
Internet Protocol (RFC791)
DES

Here are some things that were documented before they were implemented:

The OSI protocol suite
WAP
Peer To Peer (Napster et al - Intel's reincarnation of the concept)

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