pymc-labs/CausalPy

Add an Explainer section to the docs, simplify `README.md` and `index.rst`

Closed this issue · 0 comments

At the moment the docs have a nice Examples section with notebooks on the CausalPy functionality. In the language of diataxis these are good how-to guides. I think it is good that these are relatively concise guides focusing on how to use CausalPy and don't get bloated trying to provide education about the causal concepts.

That said, part of the goal of CausalPy is to lower the barrier to entry to causal inference, so it does make sense to have some form of educational/pedagogical material. This could be done with a set of brief docs in an Explainers section. These could be brief explainers, focussing on the core concepts, touch on the maths, and also provide references for further reading. Each explainer could be a notebook, but if it's code-free then there's no reason it can't just be plain markdown.

The features section in README.md and index.rst is getting a bit bloated. It initially started as a way to showcase the cool plots, but there's also explanation of each of the methods and info about format of the data needed. So I think the current content can be shifted into individual explainer pages and the current features section of the readme can be consolidated into a simple table, for example. This means we could also remove generate_plots.ipynb whose sole job is to generate the plots for the features section.