Summary and Setup
This course teaches researchers how to document their software effectively, making it accessible and understandable to others. Well-documented software promotes reproducibility, maintainability, and increased research impact through wider adoption and citation. It covers topics such as writing readable code and usage instructions.
Course summary
Software documentation helps you and others to use your software successfully in the future and to read your code ensuring that its value is sustained. This course introduces the different ways to provide other researchers with useful documentation for your software.
Research outputs often depend upon the code used to generate them. There are many advantages to making your code more readable. All kinds of research software, whether it’s code for data processing, analysis, and simulations, can be made more reproducible by providing clear context and instructions for using it.
Well-documented software is easier to maintain and has greater sustainability, which means it can continue to be used and modified for a longer period of time, despite changes in technology. If software is more reusable then it encourages others to use it for their research, increasing the number of citations of that software and its overall research impact.
Course overview
This module is part of the “Coding best practices” section of the FAIR4RS training course.
This module will introduce you to the different ways we can provide guidance to future users and maintainers of our code. These coding best practices range from the very simple, such as leaving a few handy notes, to the complex, generating a reference website that includes tutorials and a detailed reference. The right approach for your projects will probably be a blend of these, and depends on the context and your audience.
Course contents
This course introduces the different ways to provide other researchers with useful documentation for your software.
- Writing informative README files
- Writing installation instructions
- Writing usage instructions
- Writing contribution guidelines
- Improving code readability
- Doc-strings for functions
- Usage examples for functions
- Type hints
- Publishing documentation websites
- Command line interfaces with usage instructions
Related modules
There is information about publishing a software package and providing metadata and citation details in Modules 6 and 7 of this course. For more information about these topics, please refer to the following modules:
- 6 Packaging
- 7a Software repositories, DOIs, metadata, citation
- 7b Publishing a software paper
Feedback
We would like to gather your valuable feedback on this module. Your insights will help us improve future offerings and ensure they meet the evolving needs of the research community at the University. Please take a few moments to complete the feedback survey.
In the survey, we ask about how relevant the content is for your area of interest, the quality of the instruction, and the usefulness of the materials provided. We also encourage you to share your suggestions for changing the course. Your feedback is crucial to our ongoing efforts to provide high-quality research training.
Thank you for your time and participation.
Learning outcomes
After completing this course, participants should be able to:
- Write clear and concise software documentation that provides essential information to future users and maintainers;
- Understand how to make their code more readable, clean, and well-structured;
- Write clear installation instructions;
- Write effective comments and doc-strings to explain the purpose of code;
- Automatically generate documentation websites from their code;
- Create user-friendly command-line interfaces (CLIs) with clear descriptions of commands and options, along with help messages for individual parameters.
Sample code
There is an example project contained in a code repository that is hosted on GitHub at Joe-Heffer-Shef/oddsong. As we proceed through the course, we’ll create a collection of scripts similar to this. Please feel free to refer to this example to help you engage with the course contents.
Software Setup
This course may be completed using either the Python programming language or the R statistical package. Please use the tool that you prefer.
Python is a popular language for research computing, and great for general-purpose programming as well. We will be using some of the inbuilt functionality of Python 3.
The R programming language is a statistical package that is designed for data exploration, visualization, and data analysis. To interact with R, the most popular tool is RStudio Desktop.
Text editor
The Notepad text editor is installed by default on Windows. Notepad++ is a more powerful, open source editor that has a syntax highlighting feature.
Python
There is a guide for using Python on Windows in the Python documentation. Python Releases for Windows are available at Python.org.
R
Download R for Windows. We will use base R and some libraries that offer additional functionality required for this course.
Python
Please read the guide on using Python on a Mac in the Python documentation.
Text editor
GNOME Text Editor is the default app on Ubuntu since version 22.10. On other distributions, other text editors may be available, such as Gedit or Kate.
Python
Please read the guide on using Python on Unix platforms in the Python documentation.