Currently, the Notebooks are in the uncanny valley between various kinds of documentation, while being not fully satisfactory on any single "level".
They should be broken apart and cross-linked.
There should be:
- concepts (high abstraction level)
- tutorial, bite-sized examples (concrete, copy-paste-able)
- mid-level manual (explanation beyond what is in the docstrings)
- automatic docs (the technical reference, generated from docstrings)
- pure user docs (for users not writing code)