Documentation slides

[davidwilby]

will resolve #9

[bobturneruk]

Were the changes to 01 Documentation.ipynb intentional?

[bobturneruk]

Maybe consider:

Why is software documentation important to research?

With the context introduced above, we can now state the documentation problem we address in more detail: The primary purpose of research is to convey knowledge, in most cases software is a tool to utilise or extract that knowledge. Without user documentation, the software cannot be used and thus the knowledge cannot be utilised. Without developer documentation the tools and thus the scope of knowledge cannot be expanded. Without tutorials, the exploitation of the knowledge cannot be realised. This overlays and covers some of the political demands on research such as citations, collaboration and impact.

Good user documentation allows collaborators to use the software, this can then lead to citations of the software and recognition of work. Tutorials and how-to's enhance this, but also allow the expansion of impact. Whilst researchers in a similar field may know the software, and can run it with user documentation, a tutorial gets them up-to-speed quicker. At the same time, it allows non-researchers, or non-experts in the area, to use the software (and thus research and knowledge). The final type of documentation is developer documentation, which allows potential collaborators or bug fixers to know how to modify the software. At a fundamental level it can better allow users to understand and use the software, but also makes it clear to those that would like to expand the software how to do that. This can result in a higher impact for the software as more features are added, or more collaboration and citations.

from https://www.software.ac.uk/blog/2019-06-21-what-are-best-practices-research-software-documentation

[davidwilby]

Were the changes to 01 Documentation.ipynb intentional?

Just the change to line 20 to be more relevant to this particular course.

[bobturneruk]

@davidwilby - some merge conflicts here. I'll fix them if you don't get there first!