Repository navigation
Diátaxis: Where are we? #33
Description
Activity
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. :)
Reacted by Petr Viktorin, Mariatta, Erlend E. Aasland and Manuel KaufmannI 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-structureWorth reading before we start any actual restructuring.
Reacted by Erlend E. Aasland and Manuel KaufmannThis was discussed at the May 2022 docs community meeting. General consensus was to continue discussion and begin with applying concepts to new documentation.
Reacted by Ezio Melotti, Petr Viktorin and Erlend E. AaslandNoting this issue on HOWTO as related to this topic: python/cpython#114976
Reacted by Erlend E. Aasland
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.