> It turns out that these simple changes are hard! Not just in identifying the piece of code to modify, but that man pages are often incomplete or unclear.
This is a great shame. I like OpenBSD's approach to man pages - incorrect documentation is a bug and can be as severe as a bug in code; correct documentation is important.
Fixing up man pages is something that non-technical volunteers could help with, except when it's hard to grok what the code actually does vs what it should do.
> Fixing up man pages is something that non-technical volunteers could help with
Another problem with that is that most tools used in this process are made with technical users in mind. A lot of people can expand documentation, but sending manpages patches in a bug tracker is a technical step.
Comments
> It turns out that these simple changes are hard! Not just in identifying the piece of code to modify, but that man pages are often incomplete or unclear.
This is a great shame. I like OpenBSD's approach to man pages - incorrect documentation is a bug and can be as severe as a bug in code; correct documentation is important.
Fixing up man pages is something that non-technical volunteers could help with, except when it's hard to grok what the code actually does vs what it should do.
> Fixing up man pages is something that non-technical volunteers could help with
Another problem with that is that most tools used in this process are made with technical users in mind. A lot of people can expand documentation, but sending manpages patches in a bug tracker is a technical step.
If one was so non-technical as to be incapable of using diff and a bug tracker, perhaps they shouldn't be writing manpages.
Sure, they probably shouldn't be creating man pages. But they could be great at copy editing and polishing existing man pages.
Or they could be expert translators.
So it's a shame that man pages are not as good as they could be.
There are other forms of documentation, but it'd be nice if man pages were the best the could possibly be.