FOCUS AREAS

Our Documentation — the 13.1 Release

One of the three components of analytical software development at SAS, in addition to coding and testing, is documentation. Analytical product documentation is found in the SAS® Help and Documentation in each release, online at support.sas.com, and in downloadable PDF files. The 25 books that describe the 13.1 analytical products span 24,278 pages.

In general, developers of the analytical procedures write their own documentation. "Our developers begin their documentation when they put together a proposal for a new procedure," said Bob Rodriguez, Senior R&D Director. "The overview and syntax sections take shape before we even commit to the project." Developers complete the documentation when the programming is finished, filling out their chapters with getting started, details, and examples sections.

Anne Baxter and Ed Huddleston
Editors Anne Baxter and Ed Huddleston

The documentation development system used by the Advanced Analytics Division is based on the open-source LaTeX project and is supported by Principal Software Developer Tim Arnold. Regular revisions make the writing and documentation process more and more efficient. The SAS code used for the documentation examples is embedded in the documentation source files, enabling the examples to be rerun and the documentation to be updated with a single command.

After the chapters are written or revised, technical reviews commence, including those by managers and senior staff, technical support, and external experts, who often had input into the actual software. The writers incorporate the comments from the technical reviews and then send their chapters to Senior Technical Editors Anne Baxter and Ed Huddleston. "We use a lot of red ink," said Huddleston. "Often on newer developers."

There is a steady emphasis on improving writing skills and knowledge of documentation requirements in the division, and this fall we ran another series of writing review classes, taught by Baxter. In addition, Rodriguez gave seminars on developing plans for writing projects.

After final corrections, HTML file reviews, and pagination, the division documentation is pulled into SAS Help and Documentation and also placed online. At that point, Arnold ensures that a new documentation track is open for the next release, and the process starts all over again.

All this attention to the documentation is intended to produce information that is highly usable by our customers. "Having the developers write the documentation means it's written by people who know exactly what the software does," says Technical Support Manager Phil Gibbs. "And we provide feedback so it can be enhanced as needed to best serve our user community."

Here are a few highlights of the 13.1 analytical product documentation:

Bob Rodriguez and Guixian Lin
Bob Rodriguez and Guixian Lin share review notes

  • The SAS/STAT® documentation includes a new chapter devoted to customizing Kaplan-Meier survival plots.
  • SAS/STAT and SAS/ETS® documentation have separate volumes for their high-performance procedures, which are included for use in single-machine mode.
  • SAS/OR® 13.1 User's Guide: Mathematical Programming includes a new chapter on the (experimental) network solver, which makes the network algorithms from PROC OPTNET accessible through the SOLVE statement in PROC OPTMODEL.
  • SAS/OR® 13.1 User's Guide: Mathematical Programming Examples includes five additional examples.
  • SAS/IML® 13.1 User's Guide includes a new chapter titled "Statistical Graphics" that shows how to create statistical graphics directly from data in SAS/IML vectors or matrices.

Using SAS® and LATEX to Create Documents with Reproducible Results

Reproducible research is an increasingly important paradigm, and tools that support it are essential. Documentation for many SAS analytical products has long been created from a single-source system that embeds SAS code in LaTeX files and generates statistical results from those files. This system is now available to SAS users as an open-source package. The system automatically generates the SAS program file, which includes SAS macros that use the ODS document for capturing the output as external files. Listing and graphic tags display the captured tabular and graphical output. This paper describes how to access and implement the package, and it illustrates typical usage with several examples.