Re: Hurd documentation roadmap
Hi!
>>>>> Matthias Pfisterer writes:
MP> - who maintains the Hurd pages on the GNU website?
Those pages were originally written by Trent Fisher, then modified by
various GNU people when they moved to www.gnu.org. Then I updated
them with the information that I had as of last July or so. Since
then, I haven't really ``maintained'' them, but I touched them last.
Basically anybody with accounts on www.gnu.org has permission to
modify web pages, at their discretion. Of course, it's best to talk
with other people before doing something singlehandedly. I created
that set of pages, then asked for comments before replacing the old
ones.
MP> - why are there two almost identical FAQs on Hurd? Can we merge
MP> them?
I don't think they should be merged, but rather, they should be
reorganized. The basic idea in having two FAQs was not so they could
be identical... the ``Debian GNU/Hurd FAQ'' was for issues
specifically relevant for the Debian distribution of the complete GNU
system.
The ``GNU Hurd FAQ'', on the other hand, was going to answer questions
specifically about the Hurd kernel servers, which would be relevant
regardless of whose GNU distribution you are using.
MP> - should we say "Hurd" or "the Hurd"?
This is a great question for the GNU Hurd FAQ. ;)
The word _Hurd_ is a noun, so when you're talking about the Hurd
itself, you should always say _the Hurd_. My authority is learning
from example by
``This is the Hurd. Welcome.''
``Cross-compiling the GNU Hurd''
``I wonder what would happen if I ran the Hurd on nautilus...''
``... the pragmatic realities of system architecture in the Hurd.''
However, like many English nouns (all of them, if you speak hacker
jargon), you can also use the word _Hurd_ as an adjective. ``I work
on the Hurd'' can just as correctly be said as ``I'm doing Hurd
work''.
``Hurd public relations''
``interested in Hurd programming''
``Miles had set this up for Hurd snapshots a while ago...''
``a Hurd system''
I recognize that the above uses might be confusing to a non-native
English speaker, but they are actually quite standard. Think of a
word like _government_.
MP> - what do you think about seperating an "installation manual"
MP> from the "Hurd reference manual"?
Yes, that's a good idea. Distribution-specific installation manuals
will have to be separate from the generic reference manual. However,
like all GNU software, we also want to have complete documentation for
the Hurd itself available in the Hurd tarball.
It should be possible for somebody of reasonable skills to read the
included Hurd reference manual from cover to cover, and understand the
complete architecture and implementation of the Hurd.
This means the manual must document user programs that come with the
Hurd, kernel servers, libraries, and RPC interfaces. The GNU libc
documentation as a good example of what this kind of documentation
looks like. It is fine to duplicate things like the Hurd boot process
in a separate manual, but it is important not to leave gaps in the
official manual.
If you write an install manual independently, that's fine... just
remember that all the Hurd-specific details should also end up in the
official reference manual, and all the Debian-specific details should
eventually end up in the Debian install guide.
Thanks for asking,
--
Gordon Matzigkeit <gord@fig.org> //\ I'm a FIG (http://www.fig.org/)
Lovers of freedom, unite! \// I use GNU (http://www.gnu.org/)
[Unfortunately, www.fig.org is broken. Please stay tuned for details.]
Reply to: