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. The episodes in this module cover topics such as writing readable code and providing 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 FAIR2 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 some 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

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

For the complete catalogue of training courses, please browse the Research Computing Training.

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.

Key Points

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 documentation 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

An example project is available on GitHub at Joe-Heffer-Shef/oddsong. Throughout the course, we will build a similar collection of scripts. Refer to this example as you work through the course.

GitHub account

This course uses GitHub to host and share code. Please sign up for a free GitHub account if you do not already have one, and sign in before the course begins.

See the GitHub module of the FAIR4RS course for further guidance.

Software Setup

You can complete this course using either Python or R — choose whichever you prefer.

Python is a popular general-purpose language widely used in research computing. This course uses the built-in functionality of Python 3.

The R programming language is a statistical package designed for data exploration, visualization, and data analysis. The most popular tool for working with R is RStudio Desktop.

Text editor

Visual Studio Code is a free, open-source editor with excellent support for Python, R, and many other languages. It is the recommended editor for this course. To enable syntax highlighting and IntelliSense (autocompletion and tooltips), install the Python extension and/or the R extension from the VS Code Marketplace.

At the University of Sheffield, Visual Studio Code and RStudio Desktop are available on managed computers via the Software Centre desktop shortcut.

Python

See the using Python on Windows guide in the Python documentation. Python Releases for Windows are available at Python.org.

R

Download R for Windows. We will use base R together with a few additional libraries needed for this course.

Text editor

Visual Studio Code is a free, open-source editor with excellent support for Python, R, and many other languages. It is the recommended editor for this course. To enable syntax highlighting and IntelliSense (autocompletion and tooltips), install the Python extension and/or the R extension from the VS Code Marketplace.

TextEdit is installed by default on macOS.

Python

See the using Python on a Mac guide in the Python documentation.

R

Download R for macOS and RStudio Desktop.

Text editor

Visual Studio Code is a free, open-source editor with excellent support for Python, R, and many other languages. It is the recommended editor for this course. To enable syntax highlighting and IntelliSense (autocompletion and tooltips), install the Python extension and/or the R extension from the VS Code Marketplace.

GNOME Text Editor is the default editor on Ubuntu 22.10 and later. Other distributions ship alternatives such as Gedit or Kate.

Python

See the using Python on Unix platforms guide in the Python documentation.

R

Download R for Linux and RStudio Desktop.

Google Colab

Google Colab is a browser-based cloud notebook service.

VSCode Web

Visual Studio Code for the Web is a browser-based development environment, available at vscode.dev.