What recommendations can we take home?
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.