Re: 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.
How about this simple pipe
dpkg -L PACKAGE | egrep '^/usr/share/(info|man)/'
as a starting point?
Tragically, here I am in April 2005 with essentially the same problem,
and the same shortage of information. I basically lucked into this
discussion thread via google. I honestly can't see the viability of the
replies given to Otto Wyss. There _is_ a documentation problem. Packages
don't have an easy (end user) way to list what is in the package, or a
standard for useful overview or mechanisms. To shout him down, and then
to provide (admittedly useful, but certainly not end-user friendly) info
is counter productive. Sure he came off a little as telling package
maintainers what to do. Sure, his suggestion (which places him in the
top 1% of complainers) does not fit in to the carefully considered
packaging strategy being adhered to by you all.
I have yet to find out, for example which files I need to fiddle with to
fix my autoloading problem of certain modules. I need a debian specific
overview of where to put my device specific 'aliases' and 'options',
especially since some packages I am playing with are not debian
friendly, or were designed for prior kernels/modutils. I am almost
certain that this info exists somewhere. It is just not apparent where,
and google is still a somewhat clumsy tool for this job.
I _do_ appreciate the fine work done by mostly volunteer maintainers. I
do understand that documentation gets short-shift in favour of
functionality. However, Linux is (in my opinion) to the point where
lacking documentation might be hindering adoption /more/ than lacking
functionality. I therefore humbly suggest that in this case, MS has done
some things right: by enlisting their ordinary users in usability tests,
they have seriously re-engineered the way many things worked in windows.
Now we all know there are still many ways windows falls far short. This
is an opportunity. Linux enthusiasts /must/ listen to their struggling
users if they have any desire for the wider adoption of linux.
Remember that the average Linux enthusiast spends only a fraction of
his/her time installing/configuring a particular device/subsystem. They
will typically spend many more hours productively using their software,
and almost no time fixing it because it broke itself or was broken by
insertion of other software. Therefore, almost no-one will have the
level of deep familiarity with any particular subsystem that the device
maintainers have. Even to the point of not knowing what questions to ask
(thus eliminating even google). I wrestle with this issue regularly,
especially as the kernel is moving fast, and software is playing
catch-up, and I consider myself quite knowledgeable.
Dominic Amann, Linux Based Solutions Ltd., <http://www.lbs.ca/>
18 Candlewood Cr, Toronto, ON M3J 1G8
Tel: (416) 678-2297