I think a good first step would be to survey what we already have:
- What “patterns” are we using? Different documents use different “patterns”, such as:
- introduction/overview → reference → examples (e.g. the
csvmodule and thesocketmodule) - basic examples → reference (e.g. the
jsonmodule) - separate reference and how-to (e.g. the
loggingmodule)
- introduction/overview → reference → examples (e.g. the
- Which of these “patterns” are closer to the Diataxis model? Which ones seem to work best? Can we recommend a specific pattern to follow consistently?
- What documents can benefit from an update (or an overhaul)? What are the longest documents? Can we reorganize/split them following the Diataxis model?
- Are there already open issues on the tracker about reorganizing certain docs? Which documents/modules have the most issues?
- Are there other metrics that might give us some useful insights (e.g. number of page hits or StackOverflow questions)? Which documents should we prioritize?
- Do the translation teams have any feedback about which documents can be improved, since they are going through all of them already?
The answers to these questions will help us identify some documents that can be improved/reorganized/split, establish some guidelines, priorities, and update paths that we can follow to make our docs more consistent and easier to navigate.
That said, I’ve been also thinking how examples fits in the Diataxis model, since I find them quite valuable and I think we should add more.
A good portion of our documentation falls into the “reference” quadrant, and About reference - Diátaxis seems to suggest that examples should be included there – at least when they focus on individual APIs. However we also have more complex examples that might fit better into an how-to section (or page).
Should we strive to add an “Examples” section to each module? Should examples about individual APIs be kept inline or grouped in this section, in order to make the reference more compact and easier to navigate?
I guess the answer might change depending on the individual documents, but I’m curious to hear if you have any feedback about this.