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: and click on "news" or

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.


The Open Global Glacier Model

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


  • 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:

Decentralized content example:
Clubes de Ciencia Peru with Lizz Ultee

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

Be prepared for
long-term support

The invisible cost of maintenance and support
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!