Documentation

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 which reflects its health and mirrors the livelihood of the software ecosystem with regular updates.

Ideally, the documentation not only offers brief and informative guidelines to help busy users achieve their goals rapidly but also 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 documents. The documentation can also be complemented by short video tutorials or brief blog posts with practical examples to further help the users.

The developer documentation, on the other hand, involves several more detailed components:

  • Build requirements and dependencies
  • How to compile/build/test/install
  • How to use the software
  •  More detailed practical examples

In addition, the developer guides should also delineate the application programming interface (API) which paves the way for the developer community support and collaboration to further implement and maintain bits and pieces within the software infrastructure. 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 which is not an easy task, especially for large and fast-moving code bases tied with agile software engineering practices. However, slightly out-of-date documentation is generally preferable to no documentation. It is recommended that the examples provided within the documentation are compiled and tested regularly in order to maintain the quality and usefulness of the documentation over time.

Popular documentation packages:

Examples of good documentation: