[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Re: Removing the manpage requirement for GUI programs?

2010/2/27 Josselin Mouette <joss@debian.org>:

> GUI applications usually take only a few simple command-line options,
> and more importantly, when you use a modern development framework, these
> options will always be documented correctly with the --help switch.

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.
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.
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.
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

> 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.


Reply to: