This section is linked from the end of https://matplotlib.org/devdocs/users/explain/axes/axes_intro.html#axes-limits-scales-and-ticking

Marking Release Critical for 3.8 as we shouldn't release the 3.8 docs with the holes in the TOC.

Um I think we could handle the 3.8 concern by just dropping the Axis doc and calling it a day.

I'm really concerned that this is pushing even more tutorial like content into user explain and blurring the tutorial/explain/examples lines even further - which I think makes it even harder for users to sort through where they should look to find these things. Eta: what I mean by that is there's a lot on how to use something and generally not that much on what it is - ETA2: for example you basically say that a scale is a scale, assuming that the reader knows what matplotib means by scale relative to every other visualization library (and that's assuming MPL isn't their first one).

Just like in #26196 you proposed that me and Melissa come up w/ a full proposal for the dev docs re architecture, what's your vision for user vs tutorial and how these things fit where?

The vision is that the user guide be an actual user guide that people can read through in a sensible fashion and get a comprehensive view of features of the library. As opposed to the grab bag of weird things that is in it for 3.7.

Tutorials should actually be tutorials that walk through a process. I wouldn't call most of what is in the "tutorial" tab actual tutorials; they contain info that should be in the user guide, but historically were not because they were easier to write in python/sphinx-gallery than rst. Most of the substantive tutorials have already been moved to the user guide. This PR addresses a few gaps that didn't already have "tutorial" material written.

Examples should just be standalone examples, and I don't believe there is anything to prevent them from appearing in both the example gallery and the users guide, which is basically what I have done here.

I think we could handle the 3.8 concern by just dropping the Axis doc and calling it a day.

I think a User Guide would be better if it includes information on manipulating the scale and changing the ticks.

So posted this in an edit cause didn't see your comments and will post here instead., I'm sorry if I'm coming off as dismissive of all the work you've done here. I think the contents generally good and it's probably worth having it somewhere - I'm just not sure if it belongs in the user guide w/o some more explanatory framing.

i think a User Guide would be better if it includes information on manipulating the scale and changing the ticks.

Eh, I think if the user guide tells the reader that what matplotib is calling a scale is the coordinate system of the graph, and that these are the attributes and behaviors of the coordinate system, then we're giving them the grounding in the concept to empower them to look through the tutorials and examples and API.

Same w/ changing ticks - we already have lots of examples of how to do that in the specific, but we're missing a "here's the general pattern. Ticks are used to label points of the scale and in matplotib are encapsulated as X objects. Ticks can be positioned using Locator objects e.g. code just showing setting one locator,
ticks can be formatted using formatter objects e.g. code just showing setting one formatter, and since they're text objects they can be styled e.g. code showing just manipulating the text objects - basically a scaffolded step through of how to manipulate a tick object rather than the multiple examples where I think the individual things can get lost.

As opposed to the grab bag of weird things that is in it for 3.7

My concern is that w/o more grounding/framing, this still reads like a weird grab bag to folks who are unfamiliar with the library or new to visualization- who I'm most concerned about because the experienced folks generally find what they need in our docs. There really isn't table setting about why a reader would need to know about scales as Matplotib conceives of them, which means that the very new to visualization reader who wants to change the Y-axis limits may very well not realize that's the doc they need to read.

Im very certain what has been written here can be vastly improved. However the docs have been stagnant and paralyzed for many years, so someone has to do something. We can, of course, revert all the changes proposed for 3.8 and wait for the perfect solution, or we can muddle through with what I've done.

I think if the user guide tells the reader that what matplotib is calling a scale is the coordinate system of the graph, and that these are the attributes and behaviors of the coordinate system,

Added a bit more explanation about scales, and refer to wikipedia for the definition. I don't feel that the term "scale" is actually jargon that requires a whole definition from us, but rather is part of most high school curricula. The little bit of text is followed up by an example that ideally makes the concept clear to everyone.

By default Matplotlib displays data on the axis using a linear scale.
Matplotlib also supports `logarithmic scales
<https://en.wikipedia.org/wiki/Logarithmic_scale>`_, and other less common
scales as well. Usually this can be done directly by using the
`~.axes.Axes.set_xscale` or `~.axes.Axes.set_yscale` methods.

Same w/ changing ticks - we already have lots of examples of how to do that in the specific, but we're missing a "here's the general pattern.

With regards to ticks, the explanation walked through is what 95% of people want to do, which is manually set the ticks. The Locators and Formatters are then shown as more low-level and automated ways of doing the same thing.

Certainly we can add more info to these two new pages via follow-up PRs. I don't feel that should block this PR, which perfect or not, I think adds useful information to the user docs at the correct place.

However the docs have been stagnant and paralyzed for many years, so someone has to do something

I've been for years trying to get us to hire an information architect and this years GSOD stemmed from that. My motivation is that we have a ton of documentation, but it's not really clear what we have, and so I wanted all of us to have a better grip on what it is we have before we write more docs.

This is because a pretty common complaint we get from users who aren't yet familiar w/ matplotlib is that our docs are overwhelming and they're unsure where they're supposed to start (matplotlib/mpl-sphinx-theme#72 is an attempt to roadmap). That's why I'm concerned that adding more docs could be a net loss because they could potentially turn off the users who we're not already reaching with all our other docs and that's why I'm so insistent that this section be the baby steps lets try to make it not overwhelming section. A lot of my issues with content are the same as in my review for #26110

Especially stuff like this where we have a whole section in the gallery https://matplotlib.org/devdocs/gallery/scales/index.html
I don't want the content to be identical because that creates an extra maintenance burden of making sure that they stay in sync because giving two different explanations for the same thing would be deeply confusing, as would giving two different methods. I also think it's a really inefficient use of our time to write and maintain the same document twice - and it doesn't help our users much if the docs are written for the same audience.

Like this has a ton of cognitive overhead for a new user trying to learn setting manual ticks:

fig, axs = plt.subplots(2, 1, figsize=(5.4, 5.4), layout='constrained')
x = np.arange(100)
for nn, ax in enumerate(axs):
    ax.plot(x, x)
    if nn == 1:
        ax.set_title('Manual ticks')
        ax.set_yticks(np.arange(0, 100.1, 100/3))
        ax.set_yticks(np.arange(0, 100.1, 100/30), minor=True)
    else:
        ax.set_title('Automatic ticks')

If this is aimed at a new to the library user, who presumably doesn't know matplotlib well, I worry the above is gonna make them think the library is too complicated for them and they'll peace out. And I think being a bit verbose while also decomplicating would teach them more. Something like (and I edited to put the first in a loop since that's not the important thing here)

We create 3 plots to illustrate the three ways we support setting ticks. 
In this example we use the y axis, but we have equivalent methods for the x and z axis. 

* ax1: automatic 
* ax2: manually using `set_yticks` and `set_yticklabels`
* ax3: using `Locator` and `Formatter` objects:

We plot the same diagonal line going from 0 to 100 on all three::
  
 fig, (ax1, ax2, ax3) = plt.subplots(3) 
 for ax, label in [(ax1, "Automatic"), (ax2, "Manual"), (ax3, "Object Oriented")]:
   ax.plot( np.arange(100), np.arange)
   ax.set_title(f'{label} ticks')


On *ax2* we will manually set ticks at every 100/3 mark using the `set_ticks` method::

 ax2.set_yticks(np.arange(0, 100.1, 100/3))

Then we manually set the labels for these ticks using the `set_ticklabels` method::
        
 ax2.set_yticks(np.arange(0, 100.1, 100/30), minor=True)

On *ax3* we use `Locator` and `Formatter` objects to customize where ticks are placed. 
We have many, see (ref or doc) for details, here we show one to illustrate how they are generally used. 

On *ax3* we use the `MultipleLocator` to place a tick at every 100/3 mark on the major axis::

 ax3.yaxis.set_major_locator(ticker.MultipleLocator(100/3))

On *ax3* we use a string formatter to append the unit to every tick mark::

 ax3.yaxis.set_major_formatter('{x} steps')

Requests for more stepped through examples came up a lot in GSOD interviews and is embedded in the #11654 and I think it stems from us not walking through how the library pieces get put together, and I think that's what the guide is for. I know it's infinitely more tedious, but I also think this is the gap we're currently trying to fill with the scipy tutorials and is the gap the blogs and books are trying to fill. We don't need the locator/formatter references replicated - we already have those can link out to them, but we need to explain why we're linking out to them and help folks read those examples.

Most of these concerns seem larger scale than this PR - the decision to reorganize was made quite a few months ago, and we should decide before 3.8 whether to keep it or revert it, but I would argue the current organization is definitively better than what is in the 3.7 docs.

The specific criticisms about this PR, which I believe is basically that it does not do things in a step-by-step manner enough, is something I would totally welcome follow-up PRs for. But I think the basic information is there such that it's not an embarrassing gap, and I think the organization is reasonable.

The other specific criticism is that it overlaps the Examples. I don't think that is a problem in any sense, either didactically or from a maintenance point of view. I think a user guide needs examples, and there is no reason for the examples used in the user guide to remain exactly the same as those in the Example gallery.

Although there is room for improvement (why loops? I the unrolled version would probably be clearer....), but I think this is clearly an improvement and is heading exactly in the direction of what you are describing you want @story645 .

I also agree with Jody here that there is no problem with overlapping content between examples and explain. An overlap of content is inevitable under the DIVO model because all of the same information needs to be in each of the section, but presented differently in each.

My only real comments are that there should be more links to the examples and the loop thing. Both of which can be changed later.