Comment by carlosrg
8 years ago
"Community-driven" doesn't mean mindlessly accepting every patch that is submitted. Respecting the well-known structure of man pages is a good thing.
8 years ago
"Community-driven" doesn't mean mindlessly accepting every patch that is submitted. Respecting the well-known structure of man pages is a good thing.
Most of the criticism here is exactly about how people do not like the structure of man pages for this use case. If the parent suggests contributing to man pages as a fix for these issues, "Respecting the well-known structure of man pages" goes counter to that goal and suggests that solving this issue outside of man pages actually is the better solution.
Many of these pages would make fine EXAMPLES sections for the corresponding man pages without compromising the overall structure.
It's more important that there is convention than that the convention is optimal.
If the problem is that manuals aren't user friendly enough to new users and should have more examples of common tasks then they belong in the EXAMPLES section.
There's nothing that says you need to stick to the conventional sections either. A TUTORIAL section wouldn't be out of place.