Documentation overhaul: plan of action
A suggested plan of action to better organize the docs.
Check this notebook for the proposed structured (real content is not in there yet): https://github.com/MasterScrat/getting-started
Here are the core concepts behind it, that I would be eager to get feedback on:
- It’s hard to have doc that is dense enough for experienced participants but not overwhelming for newcomers. So the repo has 2 parts: introductory notebooks, and baseline solutions that more advanced users can dive right in. Each notebook itself is split in 2 part: a code-heavy “TLDR” showing the core mechanics, then an “in depth” section covering the tricky/interesting parts in more details.
- A problem with Flatland is that the documentation is currently hard to search, not properly cross-referenced, and contains outdated code samples. As a solution, my plan is to have a single source of truth which would be notebooks.
- The notebooks will be both a way to experiment with the environment, and also the documentation itself: the static documentation will simply be notebooks rendered to static files. This ensures that the doc will be up to date with the latest release, otherwise it’ll just break and couldn’t be rendered.
- This also means that assets (images, animations) in the doc will come straight from notebooks, ie everything is reproducible, and you don’t have to chase who put what where if you want to change a figure.
Related: #311 (closed) #278 #309 #55