[loudmax]

For normal, day to day use, examples in documentation is absolute gold. As a practical matter, that's how we human learn to do things. Perhaps surprisingly, even AI benefits from examples.

Children don't learn to speak a language by learning all the grammar and conjugation rules first. They learn by repeating phrases they've heard before and they generalize. Usually we learn tools the same way. We see someone else using a tool, and we do what they're doing, and generalize.

That's not to say that man pages should consist only of examples. There are times when you really do need to understand how the tool processes corner cases and really understand how it works. But I expect most of us here can relate to the experience of opening the man page for a tool and being completely baffled by a wall of unfamiliar jargon. Most of the time you just want to see how to do the most normal common functions, especially when you're learning a tool the first time.

[pseudohadamard]

Absolutely. manpages are useful as a reminder if you already know how the command works but can't remember what option enables foo-output, but pretty much useless for figuring out how to use the command all you get is 15 pages of options and flags in a long list. This is one thing that MSDN got right, look at, for example, the page for CreateFile, I can't link directly to the examples section but drop down to the end of https://learn.microsoft.com/en-us/windows/win32/api/fileapi/... and hit PgUp a few times (I deliberately chose an extremely complex function here, the docs for most others aren't that long).