Summary

Questions

  • What recommendations can we take home?

Discussion

  • Please write your questions in the collaborative notes document.

  • Any other ideas?

    • Any incremental improvements that can benefit your projects?

    • What’s nice but overkill for your work?

    • Some of the recommendations below can be used as food for thought.

There is not the one right way: it is always a balance

Jupyter notebooks can be good documentation for scripts

  • For simple scripts and post-processing, Jupyter notebooks can form a nice self-documenting pipeline.

READMEs or Sphinx?

  • For smaller projects READMEs can be absolutely enough.

  • If the code is closed-source, you probably prefer Sphinx (or similar).

  • If you need math equations, Sphinx might be a good fit.

How to make sure that code changes come together with documentation changes?

  • Make documentation part of your code review.

ReadTheDocs or GitHub pages or both?

  • GitHub pages typically serves one version (one branch).

  • Read the Docs can serve several versions (several branches/tags) at the same time.

  • Some projects use both.