Diátaxis: Where are we?
encukou opened this issue · 5 comments
There seems to be general consensus that diátaxis is a great theoretical model for structuring documentation.
However, using it – restructuring Python's docs – is a monumental task that needs some planning upfront.
@AA-Turner mentioned on the recent meeting that it would be good to start by charting the starting point: where on the Diátaxis chart do individual sections of the docs fall?
With that info we should be able to start planning where they should fall, and restructure/rewrite accordingly.
The docs are big, so this is probably best done in some collaborative document. Anyone want to start one?
FWIW, I don't think anything about diátaxis implies having/organising the documentation as 4 sections. Instead, it's more around classifying the content of the documentation -- that there's four types of documentation and that they all have different goals / style of writing necessary to ensure that they achieve what they need to achieve.
It'd be totally reasonable for Python to not have 4 sections titled "Tutorial" / "Explanations" etc -- but I do think we should double check that we don't have giant gaps for any of the four types of documentation, in the content that we do have. :)
I believe diataxis also says to not be so fixated on the structure to begin with.
There are some good strategies here:
https://diataxis.fr/how-to-use-diataxis/#don-t-worry-about-structure
Worth reading before we start any actual restructuring.
This was discussed at the May 2022 docs community meeting. General consensus was to continue discussion and begin with applying concepts to new documentation.
Noting this issue on HOWTO as related to this topic: python/cpython#114976