Comment by nerdponx

These community projects are great ways to test potential upstream changes before trying to make a bunch of upstream changes. The maintainer of the project doesn't have to field half-baked pull requests.

I think a bigger problem with man pages is not that they are badly written, it's that man itself is not user friendly:

1. I can't immediately jump to an entry for "-o", I have to use a search expression that might or might not work.

2. I can't reliably search for all references to "-o" from its definition.

3. I can't reliably jump to the definition of "-o" from any given reference.

4. I sure as hell can't search for "output" and easily find that "-o" is the option that controls the name of the output file.

5. There is no table of contents, and even if there were, there would be no way to link from an item in that table to its location in the manual.

HTML, for whatever it's deficiencies might be, is a far superior format for disseminating documentation. The Vim manual is pretty good too, due to the use of aggressive tagging and tight integration with those tags. Funny part is that manual pages can be written with semantic markup, but the semantic meaning is discarded once the manual pages rendered. It is totally backwards, and the world is in need of a better manual page renderer.