Reorganisation of documentation.
drvinceknight opened this issue · 3 comments
I would like to propose a reorganisation of the documentation to fall more explicitly under the diataxis framework: https://diataxis.fr which indicates to have 4 sections for documentation:
- Tutorials
- How to guides
- Reference
- Discussion
In practice this would mainly be a relabelling of what we already have (recall most things are labelled as tutorials)
- The "New to Game Theory" would be our tutorial: https://axelrod.readthedocs.io/en/stable/tutorials/getting_started/index.html
- The "Research Topics" https://axelrod.readthedocs.io/en/stable/tutorials/further_topics/index.html and "Further capabilities" https://axelrod.readthedocs.io/en/stable/tutorials/advanced/index.html would essentially move to "How to" sections. (As we look through there might be some that moves to a new tutorial)
- Some of our reference section https://axelrod.readthedocs.io/en/stable/reference/index.html would move to the "discussion section" (for example the background on the tournaments etc) but a lot of it would stay where it is (for example the strategies lists etc).
This would further free us up to write more specific documentation in some places.
For example when we add a new feature we could add a new tutorial as well as a new how to guide. We could also write general "discussion" material going over the theory of Moran process etc (which would be a valuable resource in itself).
A list of examples of libraries using diataxis is available here: https://diataxis.fr/adoption/
I was also thinking of plugging in some CI checks for our documentation (spelling, prose lint etc...).
Let me know what you think.
I didn't know that site existed. Now I know where to point everyone instead of just one of his talks on YouTube!!
I didn't know that site existed. Now I know where to point everyone instead of just one of his talks on YouTube!!
It's super recent :) (I still have to go through and rename "the documentation thing" in my notes to "diataxis" 😆 )
It's always been "DDQ" in my head - Daniele's Documentation Quadrants