| site | sandpaper::sandpaper_site |
|---|
This session 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 session cover topics such as writing readable code and providing usage instructions.
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.
This session 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.
This session 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, publishing a software paper and providing metadata and citation details in other sessions of this course. For more information about these topics, please refer to the following sessions:
For the complete list of training sessions, please browse the Research Coding Course.
We would like to gather your valuable feedback on this session. 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.
::::::::::::::::::::::::::::::::::::: keypoints
After completing this session, 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.
::::::::::::::::::::::::::::::::::::::::::::::::