Re: Packages with unusable documentation
On Sun, Apr 04, 2004 at 10:35:32AM +0200, Otto Wyss wrote:
> To solve my mkinitrd problem I searched for solutions. Each time someone
> has run into my problem he was asked if module-init-tools are installed
> and each time it was answered yes. Unfortunately also each time no
> further action is mentioned.
> I looked into module-init-tools to find out what's doing. First I tried
> "man module-init-tools" which didn't work. Second I looked into
> "/usr/share/doc/module-init-tools" just to discover there is just
> useless common facts. Third I started dselect and read the package
> description which didn't help further.
> Shouldn't packages which don't provide any useable information in one of
> these three locations marked as broken with a grave bug?
What are you talking about? This package has a useful description, and a
man page for every command in it.
> IMO the best way is to have a "man <packagename>" which simply gives
> links and hints to where to look for more information, a man file with
> just a "SEE ALSO" section. Each package which doesn't do this should get
> an important bug.
> IMO a must in any case is a "/usr/share/doc/<packagename>/README.debian"
> which lists all possible "man ..." of this package. Each package which
> doesn't do this should get an serious bug.
You don't make things the way you want them by going around filing bugs with
inflated severities; you only bother the maintainers.
First, you discuss the idea with others. A discussion generally starts with
"what do other people think about this?" rather than "packages are buggy if
they don't do what I want". If others agree that it is useful and
appropriate, then you start implementing it, perhaps by sending patches to
package maintainers with patches implementing your suggestion. This way you
can try out the idea and see if it works and is useful. Any kind of global
requirement deserves this kind of peer review and testing first, don't you