search

pymc-devs / pymc-examples

Examples of PyMC models, including a library of Jupyter notebooks.
https://www.pymc.io/projects/examples/en/latest/
MIT License
259 stars 211 forks source link

change level category look #610

Closed OriolAbril closed 7 months ago

OriolAbril commented 7 months ago

Closes #607

:books: Documentation preview :books:: https://pymc-examples--610.org.readthedocs.build/en/610/

twiecki commented 7 months ago

Is this changing to numbers only? I feel that might still not be clear. We can't do words?

OriolAbril commented 7 months ago

It also adds level at the beginning of the row:

imatge

It would also be possible to use words, but it will take more time to get the css so all the words fit in a single row. If someone can do it please go for it. I think the PR at least will show how to update the jinja template

ricardoV94 commented 7 months ago

Suggestion: Keep the icons (I think they are cute), but add label afterwards: bird: Beginner bird flying: Intermediate dragon: Advanced

Second suggestion: Move the 4 label links: How-to/Tutorial/Reference... to a less prominent location? I am skeptical they are a useful navigation aid to users.

twiecki commented 7 months ago
image
OriolAbril commented 7 months ago

can we keep the type of documentation category even if somewhere else?

twiecki commented 7 months ago

@OriolAbril They still show up here: https://www.pymc.io/projects/examples/en/latest/blog/category.html or where do you think we should have them?

twiecki commented 7 months ago

For me the difference between tutorial, howto, explanation is not clear.

OriolAbril commented 7 months ago

@OriolAbril They still show up here: https://www.pymc.io/projects/examples/en/latest/blog/category.html or where do you think we should have them?

I'd keep them in the sidebar. I don't think many people will go to the category page but instead browse through categories from the sidebar. But more importantly, the way to know which are the categories of a given notebook is seeing which are highlighted in green, so now it won't be possible to see which type of notebook each one is and look for similar ones.

For me the difference between tutorial, howto, explanation is not clear.

Many of the notebooks aren't following the categories very well, but the idea is for new notebooks to follow https://diataxis.fr/ with these four types, so I think it will become quite intuitive for users. Especially given the cpython docs (discussion and devdocs preview from open PR) and the numpy docs (NEP 44) are also following diataxis (that is, they are slowly differentiating and splitting their docs following these categories).

For now I don't think it should be seen as something to use everywhere (much less start restructuring everything), but mostly as a way for us to write better documentation by keeping the audience of the docs in mind when writing them (which is the main thing diataxis helps think about).

ricardoV94 commented 7 months ago

The birds are gone :( I liked them

twiecki commented 7 months ago

The birds are gone :( I liked them

What did you like about them?

ricardoV94 commented 7 months ago

They were cute

twiecki commented 7 months ago

That they were.