The quest for scientific credit for software documentation

Description

Modern geoscientific research relies heavily on numerical computations involving complex software developed by physicists or chemists. It would seem that scientists should be well versed in ways of documenting and explaining their research. Yet, when it comes to the documentation of scientific software projects, one soon realises that scientific wisdom is spread mostly by LaTeX and that the word 'documentation' starts to mean something completely different.

Writing a documentation for a scientific project can be quite challenging. There are not that many examples of well-documented open-source geoscientific numerical modelling software projects to drew the inspiration from. Even though the scientific results should be reproducible, mechanisms that reward those who deliver well documented software are still to become widespread. The scientists are judged basing on the number of peer-reviewed papers they publish, therefore investing the time solely to offer the documentation is difficult. The documentation should include the actual mathematical equations and theory behind the software, figures documenting the scientific results as well as code listings and usage examples. The target audience may have a strong background in science, computer science, both or neither.

  • Conference: Write the Docs EU
  • Year: 2015

About the speaker

Anna Jaruga

I'm a PhD student at the Faculty of Physics working in a research group

developing two C++ libraries aimed at the atmospheric community. In this presentation I’d like to talk about our quest to link the scientific credit with the software documentation. I’d like to talk about how we tried to combine explaining scientific ideas in LaTeX with explaining API along with automatic code listings in one journal-structured documentation and how we managed to publish both the code and the documentation in public, peer-reviewed Geoscientific Model Development journal. </p> </div>

</div>

</section>

</div>