Research Software Documentation

29 April 2026 - 09:00-12:00

Portobello Centre, PC-C28 Pool IT Room (40)

DAS Team

All of our events may be recorded and shared via the University of Sheffield Kaltura platform so those who cannot attend may still benefit. We will consider your attendance implicit consent to this.

Well-documented software promotes reproducibility, maintainability, and increased research impact through wider adoption and citation. This course teaches researchers how to document their software effectively, making it accessible and understandable to others. It covers topics such as writing readable code and usage instructions.

This event is for University of Sheffield researchers and research students only.

Prerequisite skills: You will need to have some familiarity with the fundamental concepts of programming languages (basic syntax, using functions, storing data in variables). Practical examples will use Python and R programming languages. A basic knowledge of version control using Git and GitHub will be useful.

Learning Objectives

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.

This course will be run in-person.

We are delighted to be able to make free at point of use training available to the research community, to enable better software and more open, reproducible research. However, free at point of use training is not free. The cost of a course can easily run to thousands of pounds, if preparation costs are taken into account.

If you sign up for a course, please make sure you either attend or cancel your booking. Bookings can usually be managed using myDevelopment or, failing that, by emailing rse@sheffield.ac.uk.

Running courses that are not fully attended wastes our funding (which is provided by taxpayers, charities and students, amongst others) and reduces our collective capacity to improve research outputs and researcher experiences.

Persistent failure to attend booked courses might result in you being excluded from future training opportunities.

More details and registration via myDevelopment.

Course material: https://fair2-for-research-software.github.io/Documentation/