Everybody has different standards for documentation
- and if you are already using a standard you like
- don’t let me stop you. But if you’ve never used much documentation and decide that you need to do better, here’s a guideline that I developed.
I’m not the best myself at documentation
- so I hesitate to offer too much advice. But here goes anyway. Your documentation should include:
- Your name and (if you don’t mind the publicity) your contact information,
- The date you created this program (in some settings the date of last modification may also be helpful),
- A brief description of the purpose for the program,
- The programming language or statistical package that your program uses
- it may be obvious that every program in the Introduction to SAS class is written in SAS
- but this is still a good habit to develop.
- Any version requirements for your language or package (if you’re not sure
- say that the program was tested on version x.x
- but should run under any other recent version).
- specific add-ons that you needed (or state explicitly that no add-ons or libraries are needed),
- other files (e.g.
- data) that you need to run this program and what directory those files are stored in,
- An explanation of how to run this program (again
- this might be painfully obvious
- but get in the habit of doing this).
- where you can find this program (either a local directory location for a private program or a repository location if you are making the program available to anyone),
- If the program is publicly available
- restrictions on who can use this program and how they can use it,
Not every program needs all of these elements
- of course
- and you may decide that other information is equally important.
How you structure this information is not important
- but for your own sake try to develop a consistent format. I don’t have a consistent format myself yet
- but here’s an example
This is a SAS program written by Steve Simon on July 21
- 2018 and last modified on July 24
- It reads in a text file of fruit fly survival times and produces an estimate of the median and quartiles of the survival distribution. It was tested on SAS v9.4
- but should run on any recent version of SAS. It does not require any special add-ons or libraries. To run this program
- load it into the program editor of SAS and click on the run icon. This program is not publicly available. It stored in MyDocuments/survival/src folder on my laptop and requires a data file
- found in the MyDocuments/survival/dat folder.