Le jeudi 04 mars 2010 à 01:22 +0100, Luca Niccoli a écrit : > Manuals are not only for documenting command line switches, they > should actually explain how to use a program. > I found the lack of good man pages one of the most annoying and > widespread problems of OSS. > Unfortunately, this gets more and more common with GUIs, as if a > graphical program could always be self-explanatory.
No. It’s just that they ship with HTML documentation, which is much more suitable for documenting a GUI. A manual page cannot contain things as trivial as screenshots, which are mandatory. > I completely agree that a debian maintainer can't take the burden to > write every man page upstream has not written, but that doesn't change > the fact that a missing, outdated or incomplete manual is a bug - to > be forwarded upstream if possible. So far, such bugs have been mostly ignored by upstreams. And when they have not, that’s where things get worse; some upstreams integrated the manual pages and didn’t maintain them when they changed the command line switches. > As has already been noted, the policy says there SHOULD be a manual > page, so a missing one doesn't make a package RC buggy. No, but it fills the BTS with pointless bugs. I think we have better things to do with our developer time and project resources. > On a side note, I find the habit of replacing the manual with on-line > html documentation terrible - we don't live in an always on-line world > yet. HTML documentation doesn’t have to be online. Packages that do that can just copy the HTML tree in /usr/share/doc/$package. > > Manual pages, OTOH, are not maintained properly by upstream developers. > > Sadly you are right. > Please try to educate upstream whenever possible. > Writing good documentation has never been fun, but it dramatically > improves the usefulness of a program. Upstreams often write good documentation. It just happens not to be in the manual page format, which is not suitable for GUIS, but in --help output and in HTML format. Cheers, -- .''`. Josselin Mouette : :' : `. `' “A handshake with whitnesses is the same `- as a signed contact.” -- Jörg Schilling -- To UNSUBSCRIBE, email to debian-devel-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org Archive: http://lists.debian.org/1267694766.15754.13.ca...@meh
