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).
Static web generators
Sphinx, JupyterBook, Jekyll...
- 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
The invisible cost of maintenance and support
Documenting a parameterized model
Open source &
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!