Hi all, I'm looking for a style guide to writing documentation for SAS software.
Looking at docs for, say, procedures, there seems to be a common method of writing about them. For example, in this PDF book on procedures for Base 9.2, http://support.sas.com/documentation/cdl/en/proc/61895/PDF/default/proc.pdf , all the procs seem to be explained in an (overview, syntax, concepts, results, examples) format. I can work this out by example, but if I do, I'll likely miss key things like spelling conventions. Ideally I'd like to see a best practices guide for writing this sort of documentation, if one exists.
I suspect that you will find a fair amount of differences in relation to defining "best practice" for documenting code. All the way from the Bill Gates "the code is the documentation" to the "every line needs a comment" school.
Personally I would start with defining who the target of the documentation is. I might document something differently for an audience that has never used or just starting SAS (a fair number of the SAS Example programs in the documentation are on this side of the spectrum) than for an experienced SAS user or a compliance auditor.
Scope of the program may play a part as well. I have some short utility autocall macros that are 4 or 5 lines of code with one or two lines of comment on use; another that is 10 lines of code has close to 30 lines of comment because of explaining what external limitations may do cause to output.
I can't comment on the referenced website as organization IT policies result in "<url> has been blocked because the web category "Uncategorized URLs" is not allowed."
As a QA person, I would suggest that the documentation include at least what the requirements for the program are and how to maintain it, what it does and how. Having proper spacing in the code make it easier to maintain. Established naming conventions help. I wrote a couple of papers you can find at www.scsug.org
Registration is open! SAS is returning to Vegas for an AI and analytics experience like no other! Whether you're an executive, manager, end user or SAS partner, SAS Innovate is designed for everyone on your team. Register for just $495 by 12/31/2023.
If you are interested in speaking, there is still time to submit a session idea. More details are posted on the website.