Write own documentation in SAS programs

[AndersS]

Hi! Is there any good way for writing documentation, in the SAS program or next to it?

Many years ago I tried to use SAS Notepad. It was OK for documentation, but the Notepad document was NOT tied to the SAS program.

My question:  Do you have any good tips ?

At present I use blocks of comments like below:
******************************************************;
*** Test WPS_2_Excel_EXPORT.sas ;
*** ;
******************************************************;

Many thanks in advance!

/ Br Anders

[AllanBowe · Accepted solution]

Great question!   The solution we use - Doxygen and SASjs.

Doxygen is a third party utility that can generate HTML websites from program headers - like this one:  https://core.sasjs.io

We made the process simpler in the SASjs CLI by pregenerating the Doxyfile (config).  The docs for the sasjs command are here:  https://cli.sasjs.io/doc/

As you can see, it even includes a capability to generate data lineage using the program headers.

You can even generate your own diagrams using DOT language - see this page (all generated from plain text):  https://core.sasjs.io/mp__stackdiffs_8sas.html

[AndersS]

Hi! I made a suggestion to SAS, many years ago:

In the SAS editor (and in the saved programs) you should have <NOTEPAD> marks.

When clicking on the NOTEPAD mark, you open the appended NOTEPAD file, in the correct place.

This means that most of the documentation is transferred from the SAS program into the NOTEPAD window.

The SAS program can be edited independant of NOTEPAD.

NOTEPAD file can be edited independant of the SAS part.

In the NOTEPAD file there should be <SAS> mark.
When clicking on the mark, you are brought into the relevant part of the SAS program.

/Br Anders

[SASKiwi]

The NOTEPAD window is available only in the SAS Windowing Environment aka Display Manager. This is now a legacy product and many SAS installations now use either SAS Studio or SAS Enterprise Guide as their user development interfaces with SWE no longer being available to users. 

[Tom]

Feel free to mimic this style:  https://github.com/sasutils/macros

Use a BLOCK comment for the header.  Then you can include example code (ie include semi-colons).

I use hyphens instead of equal signs (more minimalist). 

I set the length of the hyphen line to about 70 characters so that it serves a reminder not to type lines of code that are too long for humans to easily read.

I do NOT waste time drawing boxes around comments.  They look ugly and always end up ragged anyway after even minor revisions.

Use macro comments for comments in the code that is intended for the programmer to read.

Use statement comments in the code for comments that are meant to be read in the SAS log, especially when using macros as they will print when the MPRINT option is on.

Use block comments for any comment that needs to placed in the middle of a SAS statement.  For example to comment the parameters in a %MACRO statement.

Do NOT add comments AFTER the code (no "end of line" comments).  Tell them what you are going to do BEFORE they see the code.  Then they can decide if that it the code they are looking for.

[Reeza]

Depending on your installation and workflow you may also want to consider a Jupyter style notebook where you can have SAS code, HTML blocks or Markdown blocks.