Building software documentation for community engagement

Lessons learned with OGGM

AGU Fall Meeting 2021
C51A - Community Tools and Products for Cryosphere Discovery and Application

Fabien Maussion and the OGGM community
Department of Atmospheric and Cryospheric Sciences (ACINN)
University of Innsbruck
Talk recording, slides and links:
oggm.org and click on "news" or
oggm.org/2021/12/05/agu21

Take home messages

1. Building scientific software documentation has never been so easy. Feel free to use the OGGM repositories as a template for your project.
2. Even the best documentation won't prevent misunderstandings and disappointments.
Be prepared for long-term support.
3. Open-source and open-science take time! We need a fundamental change in the skills traditionally valued in academia to better reward open science practices and improve code literacy.

Context

The Open Global Glacier Model

  • Modelling framework facilitating the modelling of many glaciers
  • Fully open source, using modern scientific python

OGGM-Edu

  • edu.oggm.org
  • tools and materials for instructors who want to teach about glaciers at school, in workshops or at university.

Ingredients of Open Science

  • Transparency: content/code on GitHub/GitLab with an open license allowing reuse and open review.
  • Reusability: documentation, tests, support.
  • Reproducibility: installation instructions and computational environments capsules
    (e.g. MyBinder, Jupyter-Hub).

Documentation made easy

Static web generators

Sphinx, JupyterBook, Jekyll...
Interactive tutorials:
doc.oggm.org/tutorials

Decentralized content example:
Clubes de Ciencia Peru with Lizz Ultee

Photo: T. León Rojas
Links:
  • Project website (general audience) oggm.org
  • Static documentation (potential and returning users) doc.oggm.org
  • Interactive tutorials (active learning) doc.oggm.org/tutorials
  • Community communication channels (github, Slack)

Be prepared for
long-term support

The invisible cost of maintenance and support
Code
Tests
Documentation
Image missing
Documenting a parameterized model
Click on the image to advance. Source: Anne Maussion, Atelier les Gros yeux.

Open source &
academic careers

Open science takes time! Scientific papers should be evaluated according to new standards: transparency and reproducibility of the analysis chain, availability of data/code and its documentation.
Open source takes time! The work of open source developers should be acknowledged and should become an asset for academic jobs, not a handicap.
Learning code takes time! Formal training at University and high-school curricula still not adapted to the challenges ahead - we have to close the gap and make everyone feel welcome!

Thank you!

>>>