debian-doc@lists.debian.org
Hello!
I started to work on the document hierarchy. I just started to look at all
the HOWTO's available and where I would drop them. Note that this is not the
way I will make the final draft, but it is an excellent way to start up with
something working, as there are many different documents there. I made the
following observations:
1) All proposal made yet are suboptimal to cope with the huge amount and
variety of information that is provided with a standard Debian system, for
the following reasons:
a) Variety: The documents cover a variety of topics, sometimes very
specialised. The document hierarchy should reflect this by providing
sufficient enough sections. We can't just drop all network admin stuff
in a single admin/network/ dir, because this will make it *impossible* to
find the relevant information.
Although almost no Debian system will carry all documents, every
standard system has a lot of documents installed, and therefore we should
take care that we make distinction fine enough.
b) Amount: We have MUCH documents! We have over 1600 packages. If we only
assume that every package has just one document (which is not true for many
packages), we and up with the same amount of documents to be sorted and
archived in the worst case.
Let us assume, a section may contain up to 10 documents (only a thumb
rule. 1a) forbids that we just drop ten document in a genral section before
we create subsections). Then we can have 10 packages in level one. 100
packages in level two (if level one only contains sections). 1000 packages
in level three. This is still not enough. We need *sometimes* (?) more than
three levels of ordering, sorry folks. My experience is the same (I actually
made the calculation after noticing that I had to create subsections).
Please don't jump at me --- I know that there are cases were 20 similar
documents can reside in one section, and that there are cases were just two
documents are in a section. I know that. I only speak about average
values here.
One could say that we have many packages with no or little
documentation. Well, we want to change this, or? We have to plan for the
future. Maybe we will extend the system to also let info files etc be
registered. (Maybe this will solve the problem with a flooded and confusing
info dir). With info files and man pages, and several languages, we will
have several thousands documents. So we need a sufficient big hierarchy
to carry them to the user.
In the end it will be easier for the user: He will only see 5-10 sections or
documents on a single page. Marco: Do you agree that it is a *lot* faster to
descend probably 5 levels than reading the description of 50 unrelated
documents on a single page?
How do you feel now? I was surprised by the amount of documentation
available. I think they can be organized in a useful and intuitive way. Note
that the first and probably second level are pretty straightforward (for
example Installation/Hardware), so the real depth for the reader is lowered
to probably 3.
I'm planning to give definitions for sections, so the reader can rely on the
content below. This way the reader may be able to find the information
quicker, because he will have less failures.
Note that five is probably the maximum depth, and that in many times the
depth is only three or four (counting the top level that is easy).
A different issue: Some information is some-what incompatible with Debian,
or even misleading (especially mini HOWTOS). However, we should try not to
be selective. It is not to be our judgement what information is useful for
somebody. I have a better idea: Let's mark own documents with a small Debian
logo/sign or something different. When registering the document, it should
be able to specify the "value" of the content:
Value: {Debian,Recommended,Normal,Dubious}
best good default warning! # this is the interpretation
small logo,star, nothing, warn sign # this should be put on the left of
# the documents name
What do you think?
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: