Diátaxis: Where are we?

[encukou]

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.

[encukou]

The docs are big, so this is probably best done in some collaborative document. Anyone want to start one?

[pradyunsg]

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. :)

[Mariatta]

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.

[willingc]

This was discussed at the May 2022 docs community meeting. General consensus was to continue discussion and begin with applying concepts to new documentation.

[willingc]

Noting this issue on HOWTO as related to this topic: python/cpython#114976