Key Points

Introduction

  • Documentation allows users to run and understand software without having to work things out for themselves directly from the source code.
  • Different audiences (e.g. end users, developers, administrators) interact with our software in different ways and require different types of documentation.
  • Documentation can be provided at different levels
    • code-level documentation embedded within the source code to understand the implementation details,
    • software-level documentation on how to install, use, configure and modify the code,
    • project-level documentation on how to contribute to, maintain and govern the software project.
  • A (good) README, CITATION and LICENSE files are the minimum project-level documentation elements required to make research code understandable and reusable (and research it supports reproducible).
  • Documentation frameworks such as Diátaxis provide content and style guidelines that can helps us write high quality documentation.

Example Code

  • Minimum information needed to be able to run someone else code should include the reuse licence, description and purpose of the code, installation and setup instructions (including dependencies), and usage example (how to run the code).
  • Additional information may include more detailed installation guides, API documentation or design documents, list of authors and how to cite the code (this list is not exhaustive).

Generating documentation with MkDocs

  • Static site generators (such as MkDocs) can help use generate documentation websites from Markdown files or docstrings.
  • GitHub Pages provide a free webpage hosting service for your documentation website.