Byte-Sized RSE: Software Documentation with Mkdocs

This is a Byte-Sized RSE lesson on creating software documentation with Mkdocs, part of the Byte-Sized RSE Series.

Questions

• Why is documenting software important and what is its purpose?
• Who is the audience of our software's documentation?
• What are the minimum elements of software documentation needed?
• How can we use tools like MkDocs to create documentation websites for our software?

Learning Objectives

At the end of this lesson, learners should be able to:

• Describe the main types of software documentation and identify their primary audiences, including end users, developers, maintainers, contributors and system administrators.
• List components and audiences for code-level, software-level and project-level documentation for software projects.
• Use Diátaxis documentation framework to create different types of documentation according to the needs of the reader and the purpose the documentation serves.
• Generate and manage comprehensive software documentation using static documentation website generator tool MkDocs

Slides

N/A.

Recordings

N/A.

Acknowledgements

This Byte-sized session was based on the "Software documentation" episode of ["Building better research software" course][https://carpentries-incubator.github.io/better-research-software], written by Kamilla Kopec-Harding.