Documentation

• 2022-08-31

The importance of documentation in an organization is often determined by multiple factors including the adopted software development practices (waterfall, agile etc.) and the size of the software being documented. Regardless, the documentation is a vitrine for the software that reflects its health and livelihood. A thriving software ecosystem has regularly updated documentation. 

Ideally, documentation not only offers brief and informative guidelines to help busy users achieve their goals rapidly but also includes detailed user/developer manuals to provide deeper insights into the software infrastructure. The former type of documentation is often entitled as getting started, quick guide, 10-minutes to … etc. The 10 minutes to Pandas and 10 minutes to Dask are great examples of such documentation. The documentation can also be complemented by short video tutorials or brief blog posts with practical examples.

The developer documentation, on the other hand, involves several more detailed pieces of information such as build requirements and dependencies, or how to compile/build/test/install the software. 

Documentation also commonly covers the application programming interface (API). The API reference often involves the documentation of various internal files, function and class signatures as well as the reasoning behind the naming conventions and certain adopted designs. Mature scientific and engineering libraries such as oneAPI Math Kernel Library (oneMKL) and oneAPI Deep Neural Network (oneDNN) library from Intel provide great examples of this class of documentation.

The documentation should be kept up to date with changes in the code. This is not an easy task, especially for large and fast-moving code bases using agile software engineering practices. However, slightly out-of-date documentation is generally preferable to no documentation. We recommend compiling and testing the examples provided within the documentation regularly, in order to maintain the quality and usefulness of the documentation over time.

Popular documentation packages:

• C/C++/Fortran – Doxygen
• Python – Sphinx and Read The Docs
• Fortran – Ford and Doxygen
• Julia – Documenter.jl

Examples of good documentation:

• SEAMM – (Sphinx)
• Arbitrary precision math library (arb) – (Sphinx)
• MolSSI Driver Interface (MDI) – (Doxygen)
• Fortran Package Manager – (Ford)

Documentation Tutorials:

• Introduction to Python Documentation using Sphinx from the MolSSI Best Practices Workshop
• Diátaxis Framework for Technical Documentation