[thelist] project documentation

Carol Stein techwatcher at accesswriters.com
Wed Apr 2 10:54:05 CST 2003


Hi, Ken --

You wrote: 
> Right now, I'm trying to write the style guide for them, and it's not
> easy... Why can't project documentation just go away and everyone start
> thinking like me? :)

The correct way to document a project, especially in preparing a style
guide, is to write it FIRST, or at least *as* you work (updating it as you
decide unforeseen issues). Obviously, no one does this -- which is why (as
a professional consulting documenter) I was always called in *after* the
last minute, forcing me to work 10-14 hour days to prepare the
documentation. Nevertheless, I highly recommend doing it the right way; it
really helps.

Similarly, when I wrote a program, I always put the comments up top
describing what I was about to do, then just implemented the comments to
write the code. This is a good way to avoid "spaghetti code," too. Of
course, I was using APL, so it was usually very easy to think about what I
wanted to do, and not that much harder to implement it.

One thing about developing (especially code) that I always tried to point
out to novice programmers is that once you've handled 90% of the cases, you
have about 90% of the work still to do! Exceptions, which may be very few
actual cases, always require extensive handling. A programmer who starts
out by coding (instead of documenting/planning/flow-charting) invariably
focuses on getting stuff to work for that 90% of the cases, which is why
s/he ends up with spaghetti code -- exceptions are handled piecemeal and
without foresight.

Cheers --
Carol




More information about the thelist mailing list