Hurd documentation roadmap
Hello,
After positive feedback from you, I decided to do some work on the
documentation of Hurd. Here are my plans:
1. Update Webpages and FAQ (until end of this week):
They should state that there is work ongoin to a new distribution of
Hurd, which is already considered quite stable. They should give the
reader the choice to either install the 0.2 release or the actual
development state. As an interimistic solution, for installation steps,
the documents should point to John Tobey's dump of installation
procedure.
Looking at the FAQs, I noticed that there are actually two FAQs: the
gnu-hurd-faq and the debian-gnu-hurd-faq. It seems that one is derived
from the other, the differences are quite minor, and they are even
maintained by the same man! It is very unclear to me why there are two
lists. If there were only historical reasons, I feel we should merge
them. Having one list would avoid confusion to users and also lower the
effort needed to maintain them.
And: does anybody know who is actually maintaining the GNU Hurd web
pages?
2. An Installation Guide (until end of January 1999):
This should be a single text describing the instalation in some detail
and possibly covering some special cases. It would be nice if the
described process of installation is tested to some extend. But
nevertheless, at this stage, I consider it acceptable to assume some
experience with installation of Linux systems or even the Debian
distribution. Of course this document can be based on John's
description.
3. An Installation Manual (until end of February 1999):
It should also give some introductory and background information. It
should contain an architecture overview of Hurd, background on the
booting process of Hurd, a section about troubleshooting, a section
"where to get help/further information". The long-term goal is to enable
people not familiar with Linux to install Hurd. This will presumably
require some effort and will not be met by the first version. I suggest
forking this Manual from the existing Hurd Reference Manual for the
following reason: The reference manual mainly documents the libraries
and Programming of servers of Hurd, which are below a level a normal
user will cope with. Also, the refman will, once completed, perhaps have
several hundred pages. For this, it is inconvenient for users to print
out the whole Reference Manual when they only have a problem installing
Hurd. The Installation Manual will be based on the previous Installation
Guide, augmented with the thing written above. Perhaps we can take some
sections out of the Reference Manual.
Yet another question: I found some people always saying "the Hurd" while
other always just say "Hurd". Which one is correct (if there is one
surely to be considered correct)?
Summary of questions:
- who maintains the Hurd pages on the GNU website?
- why are there two almost identical FAQs on Hurd? Can we merge them?
- should we say "Hurd" or "the Hurd"?
- what do you think about seperating an "installation manual" from the
"Hurd reference manual"?
Waiting for your feedback
--Matthias
Reply to: