I spent some time reading up on this the other day, so I think this is a valuable addition! (I wanted the probability mass function it turned out.)

https://output.circle-artifacts.com/output/job/bd0c26ea-c7d9-4cb5-8f9b-f2c8923574c7/artifacts/0/doc/build/html/gallery/statistics/histogram_normalization.html#sphx-glr-gallery-statistics-histogram-normalization-py

The reason I keep hammering on scoping/chunking/headings is the same reason I'm reorganizing the contributing docs so that information is better binned -> otherwise my brain will just gloss over the content even when I'm trying really hard to figure it out because issues withworking memory are really common for folks with dyslexia, burnout, or ADHD (👋).

A very very low hanging fruit way to make the docs more accessible is some anchoring through titles and headings. Nothing complicated, just tell folks what they should be focusing on/picking out from a subsection/example. Smaller/cleaner examples would be great too, but subheadings are I don't think a big enough ask to be out of scope & much easier to put in now then on a new cycle. ETA: And I'm specifically making this ask of Jody b/c he's an experienced educator and technical writer - I wouldn't necessarily make this ask in other contexts.

The reason I keep hammering on scoping/chunking/headings is the same reason I'm reorganizing the contributing docs so that information is better binned -> otherwise my brain will just gloss over the content even when I'm trying really hard to figure it out because issues withworking memory are really common for folks with dyslexia, burnout, or ADHD (👋).

The goal of this example is not to provide a random-access reference. That is already in the API docs. The goal is to explain carefully what the normalization options do so that we can point folks who ask why we normalize histograms the way we do towards this reference for an explanation. I consider this a relatively advanced topic, and I think breaking it into more sections or subsections would be more distracting than helpful.

I consider this a relatively advanced topic

That's mutually exclusive from its accessibility in the universal design context?

I'm not saying make the text accessible to folks who don't have the mathematical background or Python knowledge to parse it, I'm asking that you make it more accessible to folks who's brains may be wired a bit different.

Plenty of writing on advanced topics (and most academic papers) break things out - a great example is7 Stages in Compositionality, which is intro to category theory

I think breaking it into more sections or subsections would be more distracting than helpful.

Is it distracting for you? Because then it's competing needs and we should figure out if we can find something that works for both of us. The lack of sections is super distracting for me, b/c I don't know where to focus or where one part ends or the other begins. And as someone who frequently links folks to our docs, it's nice when I have a specific place to do so.

Reading through it again, I'm guessing the following, which if I'm correct I don't see the harm in putting this in the document & if I'm wrong it would be helpful to have that table setting in the document.

1. Choosing Bins
   1. passing in bin edges
   2. passing in number of bins
2. Normalizing Histograms
   1. density = True and scaling
      1. explanation of integration
      2. use case: preserve shape
      3. use case: compare histograms with different bin sizes
   2. using weights
      1. explaination of pmf
      2. use case: compare histograms with different populations:

ETA: Also I could reverse outline it b/c I've read this document a bunch of times now and reverse outlined it out of frustration b/c I was trying to understand the structure. And it's clearly well structured, and my hypothesis is folks would be more enticed to read it if they could see at a scan from the outline that it's well structured.

Also I think this is a conceptual tutorial on normalizing histograms far more than a gallery example on how to use the function.

Basically going by the rough distinction on the index page of:

Demo-> plot type and example galleries
Usage->user guide and tutorials

I think this is far more usage than demo.

Thanks for the discussion. I'm going to decline to modify this example further at this time. I think the current contribution crosses the bar of being a helpful addition. I'd suggest further changes could be follow-up PRs.

I'd suggest further changes could be follow-up PRs.

If that's true, then why not do it here? There's no urgency to get this in.

ETA: Also why not move it to tutorials, where it'll be easier to find?

@story645 I do not agree with your changes. Is there a reason you are force pushing onto my branch?

Accident so I undid it?

You can rebase to drop me from the commit history but I had to rebase to drop - I was using the gh cli & didn't realize it would just push back to yours.

I'll self merge based on#27426 (review)

Reviewing this was on my todo list for yesterday and this morning, sorry I did not get to it in time.

@tacaswell, it didn't change from your previous review except for a typo.