How can we improve our docs?

[cvanelteren]

I have been at the helm on UltraPlot for nearly a year now. When I started using ProPlot some years ago, it struck me how the quality of life features are not apart of the default Matplotlib experience. However, I did notice some issues where I knew how to do things with Matplotlib, that did not necessarily carry over when using UltraPlot/Proplot.

As such, I am opening the platform to you, the community, to ask how can we improve the docs to help new users onboard quicker? Are you missing any insights or examples that would kickstart your workflow? I hope to hear from you!

[gepcel]

The doc is now very helpful. For me, the most helpful aspect of Ultraplot is that it provides a wealth of thoughtful features through a series of functions and a large number of parameters (including aliases). However, when there are too many parameters, those who are not proficient in using it may often forget which parameters correspond to which functions and what the exact names of the parameters are. It would be better if there is a quick-reference webpage or a card for this purpose.

[cvanelteren]

Thanks for the feedback @gepcel. I agree that I can get overwhelming especially when on transitions from matplotlib. In my early days I also got lost that UltraPlot sometimes deviates from matplotlib which caused a disconnect on how things are supposed to be done exactly.

Regarding you quick-reference, we do have an api page that describes everything (next to the help function that I think nobody uses anymore). The search functionality of the sphinx theme is not very helpful in my opinion, but often when you hit the right link -- the descriptions should be complete. Or are you referring to a page with all the keywords that you could click on to get to a description?

[gepcel]

I knew about the api page, and used it quite a lot. I'm expecting something more convenient. It's just quite often that I know some feature must have been supported by ultraplot, I just cannot remember where, or what the parameter name is. And it's not that easy to search. Maybe I'm expecting something that is impossible. Maybe some better organization of the api page?

[syrte]

To be fair: I do use api page from time to time when a detailed reference is needed :)

[syrte]

A gallery of plots (collected from the example plots in the doc) would be helpful.
People can skim over it quickly and see how the interesting features are implemented through uplt, esp. when they are looking for specific functions.

[cvanelteren]

I was thinking about adding this -- but it would be a lot of work I think to do this. If I can think of some sort of generator that would ideal but not sure what would be good "examples".

[syrte]

you may have already checked this, i wonder if matplotlib doc has any available tools for this. they have a nice gallary.
personally i feel the examples are good in general, maybe no need to select "good" examples intentionally.