Summary and Schedule
This is a Byte-Sized RSE lesson on software documentation with Mkdocs, part of the Byte-Sized RSE Series.
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
| Setup Instructions | Download files required for the lesson | |
| Duration: 00h 00m | 1. Introduction |
Why is documenting software important? How should we document our code? What are the minimum elements of software documentation needed? |
| Duration: 00h 30m | 2. Example Code | What is a minimum documentation needed for people to be able to reuse some else’s code? |
| Duration: 00h 40m | 3. Generating documentation with MkDocs | How can we use tools like MkDocs to create documentation websites for our software? |
| Duration: 01h 40m | Finish |
The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.
Setup
- Shell with Git version control tool installed
- Ability to navigate filesystem and run commands from within a shell
- Python version 3.8 or above installed
- Understanding of Python syntax to be able to read and follow code examples
- Pip Python package installer
- Venv Python package to handle virtual environments
- Code editor such as Visual Studio Code
Shell with Git
On macOS and Linux, some version of a shell (e.g. bash)
with Git will be available by default and no installation is needed.
If you do not have a bash shell installed on your system and require assistance with the installation, you can take a look at the instructions provided by Software Carpentry for installing shell and Git.
Python
Python version 3.8 or above is required. Type python -v
at your shell prompt and press enter to see what version of Python is
installed on your system. If you do not have Python installed on your
system and require assistance with the installation, you can take a look
at the
instructions provided by Software Carpentry for installing Python in
preparation for undertaking their Python lesson.
Pip
Pip Python package should come together with your Python
distribution. Try typing pip at the command line and you
should see some usage instructions for the command appear if it is
installed.