[gentoo-dev] Gentoo Linux documentation

Hi All,

In a few days, we're going to start an official documentation rampage, lasting
about a week.  Hopefully, in that time, we can get a whole bunch of
documentation done and on the website.  Fortunately, I'm writing an article for
IBM on the website redesign, so I can devote some time to documentation.
However, this does mean that our doc solution will be scrutinized by the world,
but I figured we're up to the task.

For a refresher, this is what everybody seems to be in agreement upon:

1. The documentation should be composed in XML.
2. We should use XSLT to translate the XML documentation into web-ready HTML.

However, we still haven't decided which XML approach to use:

a. Use our own custom "guide" format designed for our needs
b. Use the already complete docbook format for our XML

In my eyes, the advantage of a custom guide format is that it is much easier to
change/upgrade if we need new features, and is definitely going to have a
simpler, more HTML-like syntax.

The advantage of the docbook format is that it's a standard (for technical
documentation), and has a lot of features.  The downside of this is that we are
less in control of the format and we will need to learn the "docbook way" of
doing things.  Another concern about docbook -- since it has a lot more tags
than our lightweight guide format, writing docbook --> HTML XSL transforms could
be *very* cumbersome, since we will have to support all docbook tags :(  This
appears to be the major drawback to docbook -- its DTD is *huge*.

example docbook XML:

/usr/portage/app-doc/gentoo-doc/files/install.docbook

example guide (beta) XML:

/usr/portage/app-doc/gentoo-web/files/xml/install.xml

-- 
Daniel Robbins					<drobbins@g.o>
President/CEO					http://www.gentoo.org 
Gentoo Technologies, Inc.