Our first CABLE Docathon 

By Dr Claire Carouge

 A “docathon”, word invented by Aidan Heerdegen at NRI, is a hackathon to write documentation.

The ACCESS-NRI held our first docathon for CABLE on the 7th-8th November 2022. A few experts of the various scientific aspects of CABLE have been invited to come together and start the process of rewriting the CABLE documentation. Rewriting the entire documentation of the CABLE model is a part of our effort to strengthen the model curation. The CABLE documentation has not been updated following developments of the CABLE model and as such is now completely outdated. 

Learning from our mistakes, in addition to writing the documentation, we are also changing the platform and tools used for the documentation. We want documentation that is easily accessible, so we chose to publish it on GitHub pages and we use tools with common format (Markdown and LaTeX Maths). We want documentation that is developed collaboratively and close to the model code, so we host the documentation sources on GitHub where the CABLE code will soon be hosted as well. We want developers to easily know what documentation they should update, so we will rely as much as possible on inline documentation within the model code and we will develop guidelines for developers. 

In this context, our aims for our first docathon were to learn the tools, start the conversation on how best to organise the documentation, identify ways to keep people involved with the writing process beyond the docathon and finally write as much of the user guide and scientific documentation as possible. The docathon has been well received by the attendees with everyone now able to use the tools. A summary of our decisions to keep this work moving forward can be found on the ACCESS-Hive Forum. The decisions taken cover a large range from providing more guidelines to contributors to attributing oversight responsibilities for the completion of the scientific documentation to the various attendees. As a proof of the success of the docathon, we are now planning our second docathon on 13th – 14th December at UNSW.