Documenting Stored Procedures

[Peter Kleczka <knp -at- EXECPC -dot- COM>]

Hello

I'm asking for any advice that technical writers might offer regarding
creating documentation for stored procedures.  Here's my situation:

Our team is documenting functional groups of stored procedures for our
company's  multi-tiered client/server database system.  The database
server is Oracle 7.x.  The documentation audience is primarily new
database programmers.  The documentation we're producing functions both
to introduce the new programmer to the system and act as reference text.

We are trying to establish some sort of standard for the textual
descriptions for each stored procedure.  We've received some
descriptions from the programmers but they are sometimes vague.   For
instance one of the descriptions I received read something like,
"Inserts address ID's into the interface."  I changed this description
to something that would give the new programmer a more tangible feel for
what was happening in actual fields, and I specified which table was
being updated:  "Given the EEID (employee ID), sets the TRANSCODE="ADR"
(address) in the EmployeeInterface table."

This seems to work for describing some of the stored procedures we are
documenting.  But many of the procedures are more complex--they may
receive more parameters and write, update, or delete fields in multiple
table, etc.

We are wondering whether our stored procedure description should include
lists of tables read-by and written-to, whether we should document the
cursors used by the procedure, etc.  Since we have no prior experience
with PL/SQL it is difficult to come up with standards for describing
stored procedures.

If you have any suggestions or can point us to existing documentation we
might use as a model we'd sure appreciate hearing from you.

Thanks,
Pete
knp -at- execpc -dot- com

 From ??? -at- ??? Sun Jan 00 00:00:00 0000=