GLEP 13: Providing the users with a Gentoo Handbook

Status

The Handbook no longer uses GuideXML but moved to the wiki in 2014, and the Gentoo Documentation Project was decommissioned shortly after. Marked as Moribund by decision of the Gentoo Council on 2022-08-14.

Abstract

This GLEP provides a vision on the evolution of the Gentoo Documentation, namely a handbook-like document that provides its readers documentation about every aspect of the Gentoo distribution: installation, administration, application usage, development etc.

Motivation

Gentoo's current Installation Guide [1] is rapidly growing, being extended with more and more features that the Gentoo users can help with their quest for the perfect installation. This increase is needed and a Good Thing, but it makes the guide less easy to read or use as reference.

There is no reason whatsoever that this evolution will stagnate, on the contrary: people start asking why the Alternative Installation Guide [2] isn't merged into the Gentoo Installation Guide, or why the platform-specific installation guides can't be merged as they all use the same steps (with a few differences). I myself even hope to merge our LVM Guide [3] into the Installation Guide as I believe several of our users would love to use LVM on their machines, but currently don't because they don't know how handy and easy it is -- you all know this feeling :)

Rationale

To address the beforementioned problem, there are two ideas:

• Split the Installation Guide into several independent guides. For instance, we can move the information regarding the kernelconfiguration into the Kernel Guide, create a partitioning-howto that decribes the fdisk (and possibly others) steps users need to go through, etc.
• Merge all information into one Big Handbook. This is of course an idea that we borrow from our FreeBSD friends [4] who already have an extensive handbook related to their BSD-distribution.

It is this second idea that this GLEP describes.

This handbook-idea doesn't decrease the installation instructions, on the contrary, it extends them. However, by choosing a multiple-page handbook-like document, our users receive a fully integrated document that embraces everything he or she wants to know. It will also make it more easy to provide printable documentation (in PDF or other form) without loosing the comfort of having the installation documents online and on the LiveCDs.

Implementation

To implement such a handbook, the Gentoo Documentation Project [5] needs a rewritten stylesheet for its GuideXML [6] format. Since there are no problems with GuideXML itself, and since it is very flexible in its use, the recommendation to stick with GuideXML is clear. We do need some extra features in GuideXML, without breaking the current GuideXML implementation.

This last thing is important, since implementing this handbook-like document should be done parallel to the development of our current documentation: developing the Gentoo Handbook takes a long time and we don't want to force our users to use a non-usable document.

After improving the GuideXML format, the first things that need to be addressed are the installation instructions. They should be merged with other, existing guides that inform the user with installation-specific items (such as the Alternative Installation Guide, LVM Guide, Platform-specific Installation Guides, etc.)

Other chapters that need to be put in place are:

• A chapter on Gentoo Development, which embraces all current development-specific guides, such as the Gentoo Developer HOWTO, the Gentoo Policy, the Ebuild HOWTO, the Eclass HOWTO, etc. This has already been frequently asked by the Gentoo ebuild maintainers and several other Gentoo Developers.
• A chapter specific to System Administration, such as Mailserver Administration, User Administration, Printing Administration etc. We already have several guides that describe parts of these items.
• A chapter specific to Gentoo Usage, including our popular Desktop Configuration Guide [7] and several Application-specific guides.

The following sections describe these steps more in detail...

<guide>
    <chapter>
        <section>

- Software Administration

- User Administration

- Mail Administration

- Print Services

- Network Administration

- Storage Management

- Security

- Clustering

Backwards Compatibility

By making only small changes (actually extending) the GuideXML format, it is possible (and even advisable) to develop each chapter on its own parallel with the guides that are involved.

By developing the handbook in a subdirectory of the current documentation directory (for instance http://www.gentoo.org/doc/en/handbook) we maintain the current documentation. When a chapter on the handbook is finished, the involved documents can contain a big note on top, declaring that they are now obsoleted by the handbook's chapter.

However, note that this handbook does not and will not embrace all documents that the Gentoo Documentation Project produces. It is very likely that there are guides that don't have a clear position inside this handbook. Instead of forcing the guide somewhere, we should leave the guide as a stand-alone document.

Reference Implementation

This is a possible roadmap for the Gentoo Handbook:

- Improve the GuideXML format, possibly creating a handbook.xsl stylesheet
(and leave the guide.xsl as it is now).

- Implement the Installation Instructions

- Develop a consistent layout, keeping the guides that are to be implemented
  in mind.

- Include all referenced guides. Do *not* extend it yet.

- Review the installation instructions and make them official

- Extend at will :)

- Implement the Gentoo Development Instructions

- Implement the User Application Instructions

- Implement the System Administration Instructions

References

Copyright

This work is licensed under the Creative Commons Attribution-ShareAlike 3.0 Unported License. To view a copy of this license, visit https://creativecommons.org/licenses/by-sa/3.0/.