4) DDH --- Guidelines
THIS IS ONLY A PRELIMINARY DRAFT !
Marcus.Brinkmann <brinkmd@debian.org>
Debian Document Hierarchy --- Guidelines
========================================
§1. Purpose
The DDH has the task to support easy access to the information stored in a
Debian installation. It should provide a logical structure in which the
variety of documentation provided by Debian can be stored. The goal is to
minimize the time a user needs to find the correct documentation for his
problem. To make this possible, some care has to be taken when choosing the
layout of the structure and when placing the documents. Furthermore, changes
to the hierarchy have to be done carefully, as even a local change may also
affect other sections.
§2. What the DDH will provide
The DDH will provide a complete document hierarchy, consisting of
sections and links with the following properties:
a) Each section and each link will have a name, a shortname and a
description.
b) For each section a definition will be given what documents can be
installed in it. Other documents should not be installed (instead, the
DDH maintainer should be contacted if no appropriate section exists.
See also §5). No documents should be installed in or below a link,
because links are provided for user only. Instead, the appropriate section
(probably the section the link is pointing to or a subsection of it) should
be used.
c) The links will not be circular. This means, whatever way the user is
choosing down the hierarchy, he will never come to the same point twice.
As the number of section is finite, this grants that the search will
come to an end. The reason for this requirement is that it is very
confusing for the user if he finds themselves turning 'round and 'round.
Note that this does not mean that a link is not allowed to point to a
higher level in the hierarchy (as long as the branches are seperated).
It is aimed to make the choices exclusiv. This means that you can limit your
search to one section at each step. Overlaps are expressed by links between
two seperate branches and by multiple placements for a single document.
The maintainer of the DDH will actively help with the registration of documents
in the DDH. This is to ensure the over-all quality and consistency of the
DDH and to make the life easier for the developers.
§3. How the DDH Should be Displayed
The DDH has to be displayed by a program that allows navigation through
its sections to access the documentation files registered to it. For this,
the following recommendations are given to the front end:
a) The front end should have an option to enable the description of each
section and document. This description is useful for the new user of the DDH.
By reading the descriptions, the user can try to match the question to the
content of a section or document before actually entering it.
b) The front end probably wants to disable empty sections. It is free doing
so to avoid an empty page where the user has no choice but to leave,
however, it should nevertheless display the name of the section and mark
it somehow as empty (disabling a html link function is considered as
"marking"). This is to make it clear to the user that he probably found
the right section, but no useful documentation is installed. Just not
displaying an empty section means that the user does not know what to do
next, which is confusing.
§4. Maintenance of the DDH
The DDH and its supporting documents will be actively maintained by its
maintainer (currently Marcus Brinkmann <brinkmd@debian.org>. The DDH will
never be considered as `finished', as it has to be adjusted to the ever
changing situation of available documents.
For example, new sections may be needed if multiple documents about the
very same topic get available. Other sections may `dry out' because of
unmaintained and orphaned documentation. Therefore the following guidelines
apply:
a) Every released DDH carries a distinct version number. The version number
consists of two parts, a major and a minor number. Small, local changes
to the DDH that only apply to a small set of documents will lead to a
minor number change. Major number changes are only necessary if the number
of affected documents is very high or when the new DDH is not backward
compatible.
b) It is expected that minor changes will occure quite frequently (the
actual number depends on the number of new registrated documents of
course), but major changes will probably occure only in the first stages of
development, because the DDH will start with a reasonable default tree
in its initial version.
§5. Maintenance of the Registrations
Every maintainer who wants to have his document available in the DDH has to
register it via doc-base. A maintainer has to specify the following
information that is of interest for the DDH:
a) a name: This should be a short and descriptive name for the document.
The first word should be capitalized, as should be every other word
except small words like `of', `the' etc.
b) a description: The maintainer should give a short description of the
content of the document (approximately two lines). This can optionally
be displayed by the front-end.
c) one or more sections: This is the most important one to get right, as a
wrong section may make the document `virtually inaccesible' to the user (he
probably will not find it). The document has to match the section
description provided by DDH, and it should be as deep in the hierarchy
as possible.
A document may be placed in more than one section if it fits in more
than one section that do not share the same parent section (for example,
a book covering networking should not be placed in mail, news, www, ...
sections but in the parent section common to them. On the other hand,
a document that describes how to do CGI programming may be placed in the
www section of the administration branch and in the perl section of the
developer branch).
A document may not fit nicely into any of the available sections. This is a
hint that the DDH is incomplete and a section is missing or some other
section should be splitted. Also a bunch of documents may desire a section
of its own. Whenever this occurs, the DDH maintainer should be contacted
to improve the DDH.
It is considered a good idea to contact the maintainer of the DDH
whenever a new document is to be registered, especially if one of the three
points above is unclear. However, the Debian package maintainer must
contact the DDH maintainer if he wants to have new sections added or
existing sections changed. This is not intended to make his mind up for
him, but to coordinate the changes and to keep the over-all design of the
DDH consistent and bug free.
Adding a document is something that has only little effect on the whole
DDH (although a wrong decision of the section can lead to confusion), but
adding or splitting sections may affect already installed documents and may
lead to a change in the description of existing sections. In this case the
maintainer of the DDH will coordinate the changes, notify the maintainer of
the affected documents about the changes and release a new version of the DDH.
--
"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: