Summary and Schedule
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.
| Setup Instructions | Download files required for the lesson | |
| Duration: 00h 00m | 1. Introduction |
How do we provide information to users of our research
software? Why is documenting code useful for researchers? What does well-documented software look like? |
| Duration: 00h 12m | 2. Writing README files |
How do we introduce our software to new researchers and
developers? How do I structure the basic notes for my research code? What are the contents of good documentation? |
| Duration: 00h 24m | 3. Documentation strings |
How do we describe our code? How can we annotate functions in our research code? Why are documentation strings useful for research software? |
| Duration: 00h 36m | 4. Code readability |
What is code readability? How do I make my code easier to interpret? How do I explain the purpose of my code? |
| Duration: 00h 48m | 5. Contributor guidance |
How do I introduce new contributors to my research
software project? What is the best way to communicate processes such as bug reporting? Where should I write up the design and structure of the system? |
| Duration: 01h 00m | 6. Documentation sites |
How do I present comprehensive information to users of
my research software? How do I generate a website containing a user guide to my code? What should a good documentation website contain? How do I publish my software documentation on the internet? |
| Duration: 01h 12m | 7. Command line interfaces |
What is a command-line interface (CLI)? Why are they useful for making software easier to use for researchers? How do I create a CLI for my research code? |
| Duration: 01h 24m | Finish |
The actual schedule may vary slightly depending on the topics and exercises chosen by the instructor.
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.