The quest for scientific credit for software documentation


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