User guides - suggestions for explanation pages

[maximelucas]

Some of the features would benefit for a more in-depth explanation than just the API: explanations, example, use cases, etc.

I'm thinking of something along the lines of this pandas page about reshaping dataframes.

The first ones that come to mind:

• stats
• drawing

Other ideas?
Also it would be nice to have it nicely integrated in the online docs, not just as a notebook, but not sure what the best way to do this is.

[leotrs]

How is this separate from tutorials? Where in the following chart would you place what you're suggesting? https://diataxis.fr/

…

On Tue, Jul 25, 2023, 4:26 PM Maxime Lucas ***@***.***> wrote: Some of the features would benefit for a more in-depth explanation than just the API: explanations, example, use cases, etc. I'm thinking of something along the lines of this pandas page <https://pandas.pydata.org/docs/user_guide/reshaping.html#reshaping> about reshaping dataframes. The first ones that come to mind: - stats - drawing Other ideas? Also it would be nice to have it nicely integrated in the online docs, not just as a notebook, but not sure what the best way to do this is. — Reply to this email directly, view it on GitHub <#429>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AAILYABF6MZYWLXMNYWGICLXR7JRJANCNFSM6AAAAAA2XFDTLY> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[maximelucas]

Good question. In my mind it could be Explanation (bottom left).

For example, I see this page as something that explains some functionalities of the Reference. The Reference tells you what it does, the arguments, etc. Here I would explain some of these with more words, examples, etc.

We might need to clarify if there's an overlap with some of the tutos we suggested. If so, either we manage to conceptually clarify what goes where and could have, say for stats, both a tuto and a user-guide. If not, we could have one of the two.

What do you think?

[leotrs]

Yeah with this diataxis framework there is going to be some overlap. As long as the purpose of each document is clear, that's fine.