man pages started out as a problem. If you don't already know a lot of foundational stuff, it's very difficult to bootstrap yourself with it. There are so many things that say something like "see man fizzlewizzle (3)" or something. I've been a developer for nearly 40 years (mostly in Windows, barely dabbling in linux) and I've yet to figure out what the heck that number means, or how I might predict what the correct number is when I want to look something up myself.

"man man" explains the section numbers.

Maybe we need a fork of `man` that reads the page in a sexy tts voice while showing minecraft footage on half the screen.

Or AI generated animated walkthrough content straight into PluralSight...

...and I write this partly in jest as I absolutely would use that.

Cause this is what the kids want these days amirite?

> I've been a developer for nearly 40 years (mostly in Windows, barely dabbling in linux) and I've yet to figure out what the heck that number means, or how I might predict what the correct number is when I want to look something up myself.

https://en.wikipedia.org/wiki/Man_page#Manual_sections

You usually don't have to care unless you're writing them because it only matters to a user when there are man pages of the same name in multiple sections.

I think the root problem is that writing documentation sucks and people just do the bare minimum. I am hoping that AI making docs easier to create will help make them more usable all around.