Date:         Thu, 24 Dec 1998 19:30:30 -0700
Reply-To:     ecolwell@WELLSFARGO.COM
Sender:       "SAS(r) Discussion" <SAS-L@UGA.CC.UGA.EDU>
From:         Esther Colwell <ecolwell@WELLSFARGO.COM>
Subject:      Exceptional Documentation
Comments: To: sas-l@listserv.vt.edu
Content-Type: text/plain

I am automating a reporting system for a financial institution.
The code will be maintained by a relatively inexperienced
SAS programmer (as yet unknown).  There will only be one
physical file (which defines parameters for the subsequent
routines) for this programmer to edit.  I am trying to create
the most explicit, understandable documentation possible
without becoming verbose.  I probably will not be at this site
when the new programmer inherits the code.
 
Has anyone worked with exemplary documentation that you
would be willing to share with me?  In particular, I would be
interested in viewing effective layouts of instructions vs.
code, and methods of high-lighting important sections
(my current method is primitive,
 
   e.g.
 
    /* $$$$$$$$$$$$ START EDITING SECTION 1. HERE  $$$$$$$$$$$ */
 
       (code)...
 
     /* $$$$$$$$$$$$ STOP EDITING SECTION 1. HERE  $$$$$$$$$$$ */
 
 
 
Lastly, what is the best way of warning the programmer from playing with
the macro code (I am assuming the temptation may be too great for some)?
 
Any suggestions will be gratefully accepted.
 
Thank you, and I hope your holidays were happy and peaceful!
 
E.