[thelist] Basic Documentation Questions

[Luther, Ron]

Hi Gang,

Finally got enough of a 'breather' to read this thread - pretty neat.

Getting back to the 'timing' thing.

I write comments into the code as I go along to explain what sections
do. E.g. "// ** Here's where we load the date limit into the query based
on sysdate **"

I also write what I call "developer notes" into the code as I go along.
Since we often get interrupted while working on a project these help me
get back into the 'current status' of the project.  These are usually
more along the "// This function works for everything except year-end
boundaries -- fix it you moron" or "// This function is valid - waste
your time somewhere else" variety.  I strip these out of the completed
project - usually - if they deal with a future enhancement and how to do
it or where to do it, then I leave them in.


Once the code is 'relatively' done [ready for testing] - I have to put
together some "technical documentation" that I provide to the IM group.
Without this they won't 'migrate' my code to the production server - so
I have some incentive to get it done!  This document outlines all of the
tables that get touched, each of the SQL commands, each of the table
joins, each of the computed fields and the detailed computation, and
things like that.


After that little thing called "testing" is done and everyone is happy
with the final version, then I write the user documentation.  This is
the "how to use this application" document and talks mostly about
business processes.  Calculations and caveats are explained here - but
technical issues are only addressed in their business translations.
Lots of screen shots of the user controls and warning messages and
result sections kind of stuff.


HTH,

RonL.
(Oooops - back to the grind!)