Re: Re^2: dhelp directory structure
On Mon, Apr 13, 1998 at 08:18:00PM +0100, Marco Budde wrote:
> Am 13.04.98 schrieb schwarz # monet.m.isar.de ...
>
> CS> but this structure is less than intuitive (at least,
> CS> for me, but I've heard this from a lot of users too).
>
> Well, the structure is not the problem. But some developers have choosen
> the wrong diretory for their program.
For some packages, there is no best match. Where should I put svncviewer? In
X11, because it can connect to an X server, in net, because it works in a
network, or in graphics, because it is a svgalib program?
> CS> I'd prefer a much `deeper' structure. Below is a first attempt for such a
>
> Have you read the article about designing a user interface on WWW pages in
> the c#t (11/97?). A deep structure is not a good idea. Remember that the
> programs itself can create subdirectories and that we have support for
> other languages. So you have to walk to 5 or more directories in worst
> cases.
I think we can all live with this. I have no problems reading books that use
5 levels of sections. I most of the time don't have to think about it. Just
let us make sure that the up, next and back buttons do work properly.
> CS> - in some places it's hard to determine the correct section of a
> CS> manual--I'd prefer to put such manuals in several sections
>
> No, please not. This is very confusing for the user. In some cases you
> could create an own root directory.
? Did you ever wrote an index for a book? It is the most important part of a
book that transfers information. I want to find the information I seek. I
don't want to look for every possible section the program could be in. I
have an idea where to look, and it should be found there. If several
sections are appropriate, I want to find it in all sections.
I find it very confusing if I remember reading something about XXX, and not
finding a reference to it in neither XXX, nor xxx, xxy, XXx or XxX.
> CS> Here is what I'm thinking of:
> CS>
> CS> General documents [general]
> CS> Debian FAQ
> ^^^^^
> This is a document? Or a directory?
We have a document with this name. The indentation level makes it clear that
CS thinks it is a document.
> CS> Debian META Manual
> CS> Linux HOWTO's and FAQs
>
> Take for example the Debian documents. How many documents have we got? 10?
> One directory for all would be enough (both user + developer).
If we support several subdirectories, there is no need to use them all,
right. But nobody said this, too. But we have a lot of different packages in
the "doc" section. I would be very confused by all the name of the section
and the variety of packages that it contains. The debian ftp server
structure is no good document storing structure.
> CS> Installation instructions [install]
> CS> Debian Installation Manual
> CS> dselect Beginner's Guide
> CS> Debian Release Notes
>
> That should moved to the debian section.
> CS> Linux Hardware HOWTO
>
> ? That#s part of the HOWTO directory.
Yes. But it is *also* very important for installation. I have an
installation problem. Fine, I'll look in the installation section of the
debian document web server in the internet or at a friends machine. I find
the Hardware HOWTO, and I realize that my problems could be originated in a
not supported isdn card. The HOWTO section is flooded with documents and I
only look in the HOWTO section if I already know that I need a HOWTO.
Marco, I simply fail to understand why you object to order the documents in
a senseful way. The ftp structure is simply not intended to be used as a
documentation ordering. I also can't see how you can fail to see that
multiple indexing is *essential* and very, very much useful.
> CS> User's manuals [users]
>
> Why do we need such a root directory? Where#s the advantage?
The advantage is that you can constrain as a user to manuals that are useful
to you. I would be very confused as a user if I find documents about libc6
function calls if I only want to know why libc6 needs kernel-headers-2.0.32.
> CS> Developer's manuals [devel]
> CS>
> CS> C documentation
>
> [devel/c]? Not a bad idea. Maybe [devel/libs] would be nice.
Fine, you actually see that subcategories are very useful.
> CS> Perl documentation
>
> [devel/perl]? Good idea.
>
> CS> Debian's packaging system [admin/packaging]
> CS> dselect Beginner's Guide
>
> admin? -> debian
? What do you want to tell me? Sometimes I find your abbreviated stile hard
to follow. We all have little time, b I tnk w c spll a l sm th o.
I think debians packaging system is more useful for developers, whereas
debian specific instructions to mainatin the system (info about init
procedure, kernel etc) are useful in debian and probably even a seperate
admin section.
> I would suggest simply [debian/devel] and [debian/user]. It#s bad to
> create a directory for only three documents.
Others may follow. We should have a first draft, that is useful for at least
a year without major modifications and that is sufficiently complete that it
allows to place some documents in more than one place.
Thank you,
Marcus
--
"Rhubarb is no Egyptian god." Debian GNU/Linux finger brinkmd@
Marcus Brinkmann http://www.debian.org master.debian.org
Marcus.Brinkmann@ruhr-uni-bochum.de for public PGP Key
http://homepage.ruhr-uni-bochum.de/Marcus.Brinkmann/ PGP Key ID 36E7CD09
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: