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.

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

[cvanelteren]

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

One thing that I don't get is that our api is not picked up by google yet -- which would make it much easier to find results directly from a searh prompt

[syrte]

Another thing worth keeping in mind is optimizing the documentation for AI use (though I’m not entirely sure how to do that yet), somewhat analogous to SEO in the search-engine era. By the way, from my limited interaction, Gemini already seems to know how to use UltraPlot, so I guess it may already be in pretty good shape.

[cvanelteren]

We have no blocks for AI (at least read the docs does not have them last I checked). The SEO is something that has been bothering me. I recently added sphinx-sitemap(#471), will monitor it to see if it gets picked up.

[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.

[cvanelteren]

Checkout the latest docs; we have a small gallery now!

[gepcel]

Here is what I often feel very inconvenient when using matplotlib. When plotting different data, especially when plotting multiple categories of data in different subplot axes, and maintaining consistent markers or line styles (including marker, size, color, etc.) for the same category of data across different axes while cycling, along with a consistent legend, things become quite troublesome. Additionally, it's also inconvenient to use the same bins across different contour plots, filled contour plots, or pcolormesh plots in different subplot axes.

It would be better if ultraplot could provide some simple examples or documentation tutorials, or evening offering some helper functions be used in matplotlib.

[cvanelteren]

Do you have a particular test case I can look at?

[gepcel]

I'll make up some simple example and get back to you, so you can see if they're worthwhile.