Research Software Documentation

This repository contains a course on documenting research software that is part of the training provision for research computing at the University of Sheffield.

Course description

This course 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 overview

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

There is information about publishing a software package and providing metadata and citation details in Modules 6 and 7 of this course.

Contact us

Please contact Research & Innovation IT or Research Software Engineering at the University of Sheffield.