Software documentation module

[svenvanderburg]

Design

Learning objectives

• Identify the appropriate type of documentation to use for a software project.
• Describe ingredients for good software documentation
• Refer researchers to useful resources for learning more about software documentation

Types of documentation and when to use them

• Different forms:
  • Tutorials: learning-oriented, allows the newcomer to get started
  • How-to guides: goal-oriented, shows how to solve a specific problem
  • Explanation: understanding-oriented, explains a concept
  • Reference: information-oriented, describes the machinery Readme, in-code documentation, API documentation Exercise: 3 scenarios for a software project: what documentation to use?

Checklist for good software documentation

• Purpose
• Authors
• License
• Recommended citation
• Copy-paste-able example to get started
• Dependencies and their versions or version ranges
• Installation instructions
• Tutorials covering key functionality
• Reference documentation (e.g. API) covering all functionality
• How do you want to be asked questions (mailing list or forum or chat or issue tracker)
• Possibly a FAQ section
• Contribution guide

Exercise: Take the checklist and apply it to a README file of a project you know well.

Useful resources for learning about software documentation

• https://coderefinery.github.io/documentation/
• https://documentation.divio.com/

[svenvanderburg]

Comment from Jaro: this could link to the different levels of documentation for different management levels in SMP

[c-martinez]

I agree with @JaroCamphuijsen , some of the elements of the checklist are important for different types of documentation.

I could think for example of a web application:

• User documentation: the end user wants to know where to click and what result to expect
• Deployment documentation: a web admin deploying the web application wants to know how to build it and how to check it is working properly.
• Developer documentation: a contributing developer wants to know how to build and deploy the application locally, and understand the architecture of the application (where do I change the thing I want to change).

[paulmaxus]

About integrating this with the management levels of the SMP: in terms of documentation, I don't think there is a clear distinction between medium and high, so I can imagine restructuring the checklist like this:

Checklist for good software documentation (by management level)

Low (minimally required documentation)

• Developer is primary user
• One-off project or specific analysis

User documentation:

• Purpose
• Authors
• License
• Copy-paste-able example to get started

Medium and high

• Software will be used (and maintained) by others
• Research project and follow-up projects

User documentation:

• Purpose
• Authors
• License
• Copy-paste-able example to get started
• Installation instructions
• Recommended citation
• Dependencies and their versions or version ranges
• Tutorials covering key functionality
• How do you want to be asked questions (mailing list or forum or chat or issue tracker)
• Possibly a FAQ section

Developer documentation:

• Installation instructions for developers
• Reference documentation (e.g. API) covering all functionality
• Contribution guides

[paulmaxus]

Regarding the different type classes we are currently intermixing, user/developer vs. tutorial/how-to-guides/explanation/reference: isn't the checklist sufficient? The division user/developer is clear, but e.g. the distinction tutorial vs. how-to-guide is maybe a bit too theoretical and might cause confusion?

[c-martinez]

As a reference, there is an issue on The Turing Way about creating a chapter on software documentation -- probably useful to reference to it here (and contribute to its creation as it is work in progress ;-))

[c-martinez]

Hey @paulmaxus @svenvanderburg @JaroCamphuijsen -- during the last SS-NES sprint, @manuGil worked on creating the first draft of The Turing Way (TTW) chapter on Software documentation you can find it here.

Do you think you can have a look and let me know what you think? Should we polish it more? Or is it good enough that we can start a PR at TTW (and improve on it later)?

[svenvanderburg]

@c-martinez and @manuGil looks good! Yes, open up a pull request 🚀 Some general comments:

• IMO it misses an introduction. Why would you document your code/project?
• I like the distinction between code and project documentation
• It is very complete, but I think most readers won't need everything that is described. I think for the topic of documentation this should be very explicit: not all projects need extensive documentation. As a reader it feels like everything is important (especially for the project documentation), whereas most projects survive with a very basic README without contributing guidelines, a roadmap, a code of conduct etcetera. And a few comments in the code here and there.

[c-martinez]

Hi @svenvanderburg , thanks for having a look!

You are right, I had a half-written introduction which I had forgotten to finish. I've now finished it and pushed it.

If nobody has any extra comments, I will open a PR upstream next week.