BookmarkSubscribeRSS Feed
🔒 This topic is solved and locked. Need further help from the community? Please sign in and ask a new question.
factotumjack
Calcite | Level 5

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?

1 ACCEPTED SOLUTION

Accepted Solutions
juliem_sas
SAS Employee

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

 

 

View solution in original post

3 REPLIES 3
ballardw
Super User

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
Obsidian | Level 7
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
SAS Employee

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

 

 

SAS Innovate 2025: Register Now

Registration is now open for SAS Innovate 2025 , our biggest and most exciting global event of the year! Join us in Orlando, FL, May 6-9.
Sign up by Dec. 31 to get the 2024 rate of just $495.
Register now!

Discussion stats
  • 3 replies
  • 2947 views
  • 4 likes
  • 4 in conversation