[prev in list] [next in list] [prev in thread] [next in thread] 

List:       gentoo-doc
Subject:    Re: [gentoo-doc] Goal of the Gentoo Handbook
From:       Sven Vermeulen <swift () gentoo ! org>
Date:       2003-12-19 10:50:59
[Download RAW message or body]


On Thu, Dec 18, 2003 at 03:39:01AM -0500, Robert G.Waycott wrote:
> Just what is the Gentoo Handbook aiming for at this time? I have read
> everything that is on the website ... I get the impression that the
> immediate goal--undoubtedly greatly influenced by the upcoming GL2004
> release--is to pull together the best darn installation guide that can be
> made (which will be applicable to all architectures generally, give or
> take a few arch-dependent issues). Am I right? Have I missed something?

That is the vision of the first part of the Gentoo Handbook. That part, named
"Installing Gentoo", should contain everything a user should know about
installing Gentoo. It must contain all the instructions necessary for the
user to succesfully install Gentoo and elaborate on the aspects that are new
to some people.

This part however should not provide the user with all possible installation
tweaks he can do. We all know you can install Gentoo using different media,
making different choices, extending with different options. The first part
should therefore contain only the necessary information, but not all
information.

The Gentoo Handbook (as a whole) should contain "static" information
(most of them about Gentoo) that is of great use by our users. Information
that doesn't change a lot (which is of course relative due to the nature of
the Gentoo distribution) such as "Installing Gentoo", "Working with Portage",
"Desktop Configuration", "Developing for Gentoo", etc.). This doesn't mean
that all documentation will be embraced by the Gentoo Handbook, far from it.
Dozens of currently existing guides will not (erm... are not planned to) be
integrated in the Gentoo Handbook.

It must be made clear that the Gentoo Handbook is not "the future" of the
Gentoo documentation. It is a vital part of it, but we should focus to
develop more "ad-hoc" documentation for the users (in the form of guides)
which inform them how to solve certain problems, configure their environment
for a certain situation, etc.

The Gentoo Handbook is a means to provide extended information to the users
about certain subjects. It provides the documentation developer with the
possibility to elaborate on certain aspects without blowing up the size of
the page the user is looking at. With this in mind, chances are that the very
large documents (gentoo-security and desktop) will be integrated in or in the
same format [2] as the Gentoo Handbook.

Take a look at the Gentoo-specific items. Some believe that Portage is
Gentoo's core. For portage, you have two documents:
	http://www.gentoo.org/doc/en/portage-user.xml
	http://www.gentoo.org/doc/en/portage-manual.xml

I believe that the structure of those two documents is now outdated [1]
because it wasn't designed to be very elaborate. In the second part of the
Gentoo Handbook I have rewritten all Portage-specific information with the
non-developer in mind. I'm pretty happy with the result (but of course, the
real user has the final vote on this).

Other Gentoo-specific items are:
	- USE flags (http://www.gentoo.org/doc/en/use-howto.xml)
	- Init scripts (http://www.gentoo.org/doc/en/rc-scripts.xml)
	- Environment variables (http://www.gentoo.org/doc/en/env.d-howto.xml)

Those are the main Gentoo-specific guides we have. Most other guides are
more general (i.e. they can be of use for non-Gentoo users) and only contain
Gentoo-specific information when we are talking about the installation.

> Also, I have been to bugs.gentoo.org and registered. Started to submit a
> bug report, but have paused for the moment due to being a little daunted
> and cautious of the 'search' phase, which I agree is very important. I
> definitely don't want to submit a duplicate--and, thus, erroneous--bug. So
> far, I have received the 'zarro boogs,' though I am not sure if this is
> because I am just using a poor search string. So far, I have searched the
> terms 'spelling error' 'spelling' 'grammar' and the like, and cannot come
> up with any more--oh yeah, I have been searching this after clicking on the
> 'Gentoo website' portion of the categories. Should I conclude it is safe to
> submit my report?

I really appreciate that you are searching for duplicates or erroneous bugs,
but don't overdo your search. If a couple of simple terms don't provide you
with a duplicate or already-resolved bug, then go ahead with the bug report.
The editors that take on the bugs won't bite your head off (except perhaps
Erwin`, depends if he has eaten already or not - just kidding :).

Wkr,
	Sven Vermeulen

[1] Note: I don't say the documents suck. They are great and are of big
    importance for the users. 

[2] The Gentoo Security guide is a difficult guide. Security evolves
    continuously but we have little resources to update the guide over and
    over again. There are also many ways to enforce security onto a system --
    the subject is very broad. I personally believe that the security guide
    needs to be rewritten as a chapter in the Gentoo Handbook. Well, I'm
    still thinking of it, but time is lacking on my side.

-- 
 ^__^   And Larry saw that it was Good.
 (oo)                                      Sven Vermeulen
 (__)   http://www.gentoo.org              Documentation & PR

[Attachment #3 (application/pgp-signature)]

[prev in list] [next in list] [prev in thread] [next in thread]