In Estimating Norovirus Prevalence I wrote up an estimate [in] prose, though, with inline calculations, and this has a few drawbacks:
The calculations are manual, which makes it harder to catch errors.
It’s hard to tell exactly how sourcing works for inputs that are being pulled in from elsewhere.
You might want multiple estimates based on changing inputs over time.
At the NAO we also started with prose estimates, in Google Docs, but in addition to the issues above we found that the review tooling wasn’t a good fit for the kind of deep reviews we wanted. After some initial struggles we switched to Python to represent our estimates; you can see the code on github.
Documentation with inline calculation and sourcing sounds like a perfect use-case for Jupyter notebooks (Video). Have you looked at them?
Documentation with inline calculation and sourcing sounds like a perfect use-case for Jupyter notebooks (Video). Have you looked at them?
I’ve used them, and similar tools, but don’t really see the advantage over source code with comments?