Documentation

Why bother? My code is self explanatory!

  • Clarity for others (and yourself!)
  • Encourage more users - more citations & research impact
  • Improve longevity of your research

See SSI Blog “What are best practices for research software documentation?”

Who is going to use my code?

  • Future me!
  • Collaborators
  • Researchers
  • Other developers
  • Future researchers

What do they want to know?

Researchers

  • what is possible with the code,
  • how to use it,
  • the context and theory,

Developers

  • what work needs to be done,
  • how it works,
  • how to contribute.

What kind of documentation might I need?

  • Comments
  • Readme file
  • Documentation generators
  • Wiki
  • Tutorials
  • Demos