[thelist] Basic Documentation Questions

[Bill Haenel]

> I recently read a very good book called "Debugging Java"...
> ...The author suggests
> not only writing the documentation BEFORE writing the first line of code,
> but also going so far as to write the user manual before as well.
> This not only defines what the app will do, but exactly HOW it will do it,

WOW. That's quite a statement, isn't it? Especially considering Alan's
comment:

> I've tried documenting a coding project as I go, only to have the whole
> thing turned upside down because of a need to change coding structure,
> language, server platform, etc.

What I've done so far is to first outline the general concept of what the
program will do (needs), then create a flow chart suggesting how the process
might work (functions), then write the code. I've done some informal
documentation in the way of notes while creating the system, and by
commenting in the code itself, but usually the comments need to be
re-written by the time I'm done writing functional code.

Of course, I always figured I'd be a musician, not a programmer.
Plus, I probably need to consider formal education before I call myself a
'programmer'!

BH