Best Practices for Writing Documentation

[factotumjack]

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.

My goal is to write a SAS equivalent to this article, which is a support of the best practices for R documentation: http://www.stats-et-al.com/2019/04/writing-r-documentation-simplified.html

Can anyone point me in the right direction, or advise me towards some key examples?

[ballardw]

Welcome to the community.

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."

[CJac73]

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

http://www.scsug.org/SCSUGProceedings/2005/Jackson_Maintaining%20Inherited%20SAS%20Code%20-%20219.pd...

http://www.scsug.org/SCSUGProceedings/2003/Jackson%20-%20WritingSASRight.pdf

[juliem_sas · Accepted solution]

Hi,

Here are a couple of papers that might be helpful:

Peter Timusk, SASGF 2014: http://support.sas.com/resources/papers/proceedings14/1617-2014.pdf

This one, from SASGF 2017,  recommends using SAS metadata with automated documentation: https://support.sas.com/resources/papers/proceedings17/1314-2017.pdf