Instructor Notes
This is a placeholder file. Please add content here.
Introduction to good practices in research software development
Refer to this introduction
For each new tool that you introduce you can refer back to the ideas in this introduction: The tool can add overhead in simple projects, but can speed up development in more complex projects.
Modular Code Development
Document your research software
Instructor Note
Use these slides as a guidance.
The main purpose of this lesson is to make sure participants understand that DOCUMENTATION IS IMPORTANT. The goal is more to trigger participants then to teach them all the different ways one could document a project. It is good to communicate this (and that this will give more time for the other parts of the workshop).
Instructor Note
Please note that writing documentation using Sphinx is an optional part in this workshop. For some learners it is enough to know that Sphinx exists, but it is overkill for their current projects. Other learners really want to learn Sphinx and can benefit from it. In practice, teaching Sphinx can be hard, since the ReStructuredText is quite error-prone when it comes to the right indentation, number of empty lines etcetera. It is up to you if and how you want to include this section when teaching this episode.
Instructor Note
You can show what the results of this exercise are here: https://clairedons.github.io/temperature-conversion/ and perhaps explain how to add the link to the repository.
You can show the example documentation deployed on GitHub pages here: https://esciencecenter-digital-skills.github.io/good-practices-documentation-example/
Then, you can show that this content comes from simple markdown files, like: https://github.com/esciencecenter-digital-skills/good-practices-documentation-example/blob/main/doc/another-feature.md?plain=1
In addition, you can explain that with a few settings you can automatically generate documentation from docstrings. You can give https://nanopub.readthedocs.io/en/latest/reference/client.html as an example.