In the last 2 days, we had a CABLE docathon with a few CABLE experts to rejuvenate the CABLE documentation.
A new platform has been chosen (more information) with the source of the documentation hosted in a GitHub repository that will eventually host the CABLE source code as well.
The docathon was successful and has shown a lot of motivation in updating the documentation. But this is a big task and it requires some time investment from all CABLE developers and users. The goals of the docathon were:
- familiarise everyone with the chosen tools and get feedback on how best to use them
- focus on the User Guide and the scientific documentation first.
Outcomes
At the docathon, we discussed how best to keep everyone engaged with the process. We have decided so far:
-
develop a timeline for the documentation to increase visibility of shared expectations. First priorities are a User Guide, scientific documentation and a high-level flowchart of CABLE.
-
nominate Code Owners for different parts of the code that are responsible for overseeing progress in the documentation:
- Gab: driver, I/O and maybe soil
- Mengyuan: hydrology (GW)
- Juergen: POP
- Ian: roughness and canopy
- Yingping: CASA-CNP and landuse
- Jhan, Claire: Radiation and albedo
-
Create GitHub issues for each block of work so people can easily find something to work on
-
develop guides and guidelines to help people work independently: GitHub workflow cheatsheet, Markdown cheatsheet, guidelines on what to include in the scientific documentation.
-
hold a second docathon on 13-14th December at UNSW
Open questions
Resolving bug fixes in the code
While documenting various sections of the code, several improvements or bug fixes have been identified. It has been decided to simply put Warnings in the documentation about the potential issues and not to fix these directly. It is the preferred approach generally as it is very easy to loose the focus on the documentation and focus on the code itself instead. However, it is left to each writer to decide whether it is worth documenting the code as is or instead putting the effort into fixing and testing it first.
Format and location of the scientific documentation
The format and location of the scientific documentation are not yet fully decided. The preference would be for the full scientific documentation to be included in the source code to be picked up by the automatic documentation tool. This provides the easiest way for developers to be aware of the documentation and update it. The downside is the level of commenting this would add to the source code. In particular, the UM coding standards point to keeping the amount of commenting reasonable so we need to clarify with the UKMO if this approach would be acceptable. We have discussed other possibilities such as:
- use “include” files for the inline documentation. This means the scientific documentation would live in separate Markdown files but would appear within the inline documentation. The source code would simply need a one-line comment to include the Markdown file. This solves the problem of the length of the comments in the code but removes direct access to the documentation. Although it keeps the scientific documentation layout identical to the code layout which simplifies finding the part of the documentation to update when developing the code.
- use separate standalone documentation. It is very similar to the idea of “include” files but it does not force the scientific documentation to closely follow the code organisation.
Not enough Code Owners
So far we have identified no more than 1 code owner per part which is not enough over the longer term. We also have parts of the code without Code Owners: BLAZE, SLI, canopy and soil to some extent.