|
Home > Archive > Debian Developers > April 2004 > Packages with un usable documentation
You are viewing an archived Text-only version of the thread.
To view this thread in it's original format and/or if you want to reply to
this thread please [click here]
| Author |
Packages with un usable documentation
|
|
| Otto Wyss 2004-04-04, 10:33 am |
| 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?
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.
Some packages provide useful information within the description files.
Therefore long ago I've made a "dsc2man" which simply creates man files
from the descriptions. It's up to any maintainer if he wants to create
man files this way (see "http://dpartialmirror.sourceforge.net/").
O. Wyss
--
See "http://freshmeat.net/projects/wxguide" for application design
See "http://freshmeat.net/projects/wxguide-editor" for a nice editor
--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
| |
| Colin Watson 2004-04-04, 10:33 am |
| On Sun, Apr 04, 2004 at 03:33:51PM +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?
If you file a grave bug about this I shall downgrade it immediately!
> 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.
dlocate -man
> 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.
Serious bugs will likewise be downgraded. Please don't inflate bug
severities; it's extremely rude.
http://release.debian.org/sarge_rc_policy.txt
--
Colin Watson [cjwatson@flatline.org.uk]
--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
| |
| Otto Wyss 2004-04-04, 11:34 am |
| > Serious bugs will likewise be downgraded. Please don't inflate bug
> severities; it's extremely rude.
> http://release.debian.org/sarge_rc_policy.txt
I _don't_ want to file any bug, even if module-init-tools is _not_
usable. I want to discuss this matter in a way which solves this
increasing problem but it seems you aren't interested.
It is so simple to add a few starter hints (seldome more than a 10min
work) which are missing in an increasing number of packages.
O. Wyss
--
See "http://freshmeat.net/projects/wxguide" for application design
See "http://freshmeat.net/projects/wxguide-editor" for a nice editor
--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
| |
| Colin Watson 2004-04-04, 11:34 am |
| On Sun, Apr 04, 2004 at 04:37:47PM +0200, Otto Wyss wrote:
> Colin Watson wrote:
>
> I _don't_ want to file any bug, even if module-init-tools is _not_
> usable. I want to discuss this matter in a way which solves this
> increasing problem but it seems you aren't interested.
The way to start discussions isn't to say "I will file bugs at
release-critical severities", especially when people who want to get a
release out are listening ...
Lack of adequate documentation is certainly a bug, but not every bug
that annoys the submitter is release-critical, which is something I keep
having to point out again and again while going over the
release-critical bug list. (Fortunately, these days the severities are
more clearly defined so this problem is less bad than it used to be.)
> It is so simple to add a few starter hints (seldome more than a 10min
> work) which are missing in an increasing number of packages.
I won't be adding man-db(7), nor do I think that it needs
/usr/share/doc/man-db/README.Debian to tell you what you could find out
from 'dpkg -L man-db'; learning 'dpkg -L' benefits you for *every*
package, not just the ones you get changed. I really don't think other
packages should have to do this, either.
Cheers,
--
Colin Watson [cjwatson@flatline.org.uk]
--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
| |
| Tollef Fog Heen 2004-04-05, 6:36 am |
| * Otto Wyss
| Shouldn't packages which don't provide any useable information in one of
| these three locations marked as broken with a grave bug?
No, why should 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.
That's just silly.
| 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.
: tfheen@yiwaz ~ > dpkg -L module-init-tools | grep man
[snip list]
: tfheen@yiwaz ~ >
Please learn to use the tools you have available.
--
Tollef Fog Heen ,''`.
UNIX is user friendly, it's just picky about who its friends are : :' :
`. `'
`-
--
To UNSUBSCRIBE, email to debian-devel-REQUEST@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
|
|
|
|
|