I'm not sure what this has to do with Kerrisk. Software maintainers just need to simply add examples of using the software they use. They know best how it works, I don't know why this has to be met with so much friction. Like not posting images of your new game/image library. People want examples of stuff.
Because the man-pages project that he maintains provides the largest set of third-party manpages (outside the project trees themselves). The majority of manpages live either in the project they document or in the man-pages project.
> I don't know why this has to be met with so much friction.
The point of this thread is that it will often not be met with friction. Examples should be in a combination of the summary and examples sections of the manpages. (Distinct modes of operation belong in the summary, more fine-grained examples go in the examples section.
I think the hardest part is that people don't know what others don't know. When you're so close to a project, things that are obvious to you are impossible to new people, but you don't realize how impossible it is until you get that feedback.
Just start with the assumption that no one understands how to read a man page and how to translate that into a full command line operation. A simple example goes A LONG WAY.
Back in 2000-2005 I worked on the SQL Server documentation.
If I remember correctly, when we instrumented the docs we found that the VAST majority of users skipped over all the descriptions and parameter definitions, and jumped straight to the examples of usage. Turns out observation is the fastest way to learn/remember. We redoubled our efforts to include examples of more obscure usage patterns, rather than relying on wordy explanations.
That's EXACTLY what I do. I imagine there are some that are great at reading white papers, but I am not one of them, and I'm not alone. Experience > Education.
But they don't necessarily know best what usage patterns work well for people who are not maintainer-level experts.
I see a strong case for having separate texts for documenting the interface (striving for completeness and low redundancy) and introductory teaching. I don't think that I'd like seeing each man page prepended with a wordy ELIF and two pages of trivial examples. And I'm not saying this because I'd not need the ELIF, quite the opposite, I just don't think that it would be wise to mix them.
Having them maintained in one place, passed through the same distribution channels and available on the command line, now that would great of course. The minimum almost-requirement for a crowdsourcing effort for that content could be a contribution licence that is 100% compatible with the real thing, not 99%, not 99.99. Just in case.
