[gentoo-dev] GLEP 13 (brrrr) - Gentoo Handbook

[Sven Vermeulen]

Hi,

http://www.gentoo.org/proj/en/glep/glep-0013.html

You all know that our current installation guide (more precisely, the x86
installation guide) is changing almost on a daily basis. It is also a very
hot item in several discussions, because the LiveCDs are very hot.

I have recently received a mail by drobbins to not have the installation
guide grow even further, since it will become difficult to maintain, read and
follow. And as you all know I'm not someone that shrugs and follows, so I
decided to prepare a GLEP to be able for the installation guide to grow when
it wants to ;) 

This GLEP talks about the creation of a Gentoo Handbook, akin to FreeBSD's
handbook, starting with the chapter on installation. 

Now why a handbook, and what will we do about the ppl that say we copied that
idea from FreeBSD? Well, with the latter, we just say "so?" because we know
such a handbook is a frequently requested item, and it will make several of
our -- currently independent -- guides more coherent.

But the why's can be difficult. There is indeed another solution, splitting
the installation guide into several smaller guides. The reason I opt for a
handbook is because we can then enhance the installation instructions with
more, integrated information.

For instance, we can make the user choose LVM (something I know several of
our users want, but didn't know it existed until after they installed
Gentoo), and we can do it linearly, without forcing him to have two terminals
open to see if he has encountered a "different" section, as is currently the
case.

We can also make the x86/PPC/SPARC/... installation instructions more
integrated. Changes in Gentoo are felt all over the place. Currently, the x86
installation guide is the guide which is updated quickest. Other installation
guides follow with some lag. By combining all instructions and have a clear
way to denote x86-only, or ppc-only, or sparc-only sections, all
architectures are treated equally.

We also reduce the total amount of written documentation at first (later on,
it'll grow as a natural evolution because of enhancements etc.) since double
information is eliminated (if you read the ppc-installation guide for
instance, you'll notice that most of it is the same for x86 and vice versa).

Now I'm only ranting about the chapter regarding "Installing Gentoo" since,
in the GLEP, this is the first chapter that should be worked on. Later, when
that chapter is "finished" and official, the guide can and should be extended
with other chapters, such as "System Administration", "Gentoo Development",
"User Applications" and so on.

To provide the Gentoo users with such a handbook, several steps need to be
taken. First of all, a new stylesheet (with enhancements for the GuideXML
format) should be written. This stylesheet should be able to support
	- multiple pages output
	- multiple pages input
	- deeper nesting of information blocks
		(chapter, section, subsection, subsubsection)
	- in-document references
and, if possible, a way to convert it to a format that makes it easy to
convert to, for instance, LaTeX or DocBook so books can be produced better.

Such stylesheet-hocuspocus is not fantasy -- people with experience in XSL
know this isn't too hard, but it requires a little time to produce such a
stylesheet. In the mean time, development of the installation guide continues
as it is now.

When the stylesheet is finished, a first layout on the chapter should be
written. This layout can be a listing of all sections, subsections and
subsubsections and should list all guides that are being incorporated,
e.g.
	- x86 installation guide
	- ppc installation guide
	- sparc installation guide
	- alternative installation guide
	- LVM guide
	- kernel guide
	- UML guide
	- ...

Then the chapter can be incorporated. However, to make sure that this doesn't
lead to spaghetti, we shouldn't add new items yet -- this is for when the
chapter becomes official. This way we make sure that the "Installing Gentoo"
chapter doesn't stay as an unofficial-work-in-progress.

So, please read the GLEP and provide us with your comments!

Wkr,
	Sven Vermeulen

PS gentoo-dev ppl, please discuss this in gentoo-doc as this is purely
   documentation related.

-- 
    Save some animals, eat a vegetarian.