On Tue, Nov 22, 2005 at 07:47:11PM +0100, Danny van Dyk wrote:
[... About the stage1/2 instructions in the Gentoo FAQ ...]
> That's currently a stub. If i recall right, Swift mentioned on #-dev
> that he'd need to refurbish this.

Lots of heat again. Good thing, because it is quite cold here in Belgium.

When I originally created the Gentoo Handbook, I hoped that it would contain
all Gentoo-specific documentation in one place: the installation
instructions for all architectures, all possible methods. However, that
first attempt had its fundamental flaws, the major one being the stupid
believe that users wouldn't mind reading about other architectures if they
are well guided through the instructions.

So the Handbook changed and split. Architecture-specific instructions were
moved to separate files and each architecture had its own handbook even
though many parts of it were shared, allowing the Gentoo Documentation
Project to maintain all Handbooks without having one or more of them become
too outdated easily (which was what happened with the separate installation
guides).

Yet this attempt still had its difficulties: when the Release Engineering
team decided that a quarterly release was too stressful (they had to do more
packaging and deployment rather than research and development) they also
made the Gentoo Documentation Project split the handbooks in two: one which
contained the Internet-based installation instructions, using the latest
stable packages (baselayout), while the other handbook contained the
instructions that were statically bound to a certain release.

This was needed because, at that time, Gentoo had a history of changing core
system configuration too often making it too darn difficult to keep the
Handbook in good shape. Right now, I believe that those causes are invalid
and that the separate handbooks can be combined again, especially with the
request to move the stage1/2 instructions elsewhere.

I was quite reluctant to move the instructions at first, but when I found
out that the instructions were indeed not perfect, I had two choices: either
update the instructions in the Handbook to be correct, or move the
instructions outside the Handbook first (making sure that the official
installation instructions remain bugfree) and write a separate guide on
bootstrapping.

Based on the input I've gathered from the gentoo-doc mailinglist,
gentoo-releng mailinglist, Gentoo Forums and various other sources it was
quite obvious that a *very* *short* amount of users was aware of the theory
(and practice) behind bootstrapping. In fact, most saw "stage-1" as the
online drug to increate their, quoting Xavier Neys, "ePenis". And not only
that, but I also found that I personally lacked the knowledge to write
something decent about bootstrapping.

Therefore I decided to move the instructions that were in the Gentoo
Handbook to the Gentoo FAQ in the first place. I intended to have the FAQ be
accurate with the information I already had without losing anything
important. I did miss something in that procedure, namely the change of the
CHOST variable, but other than that the FAQ contains the same instructions
as were in the Gentoo Handbook.

The next step for me was (and still is) to investigate what bootstrapping by
itself means. Why whould anyone need to rebuild this toolchain twice? I
could perfectly understand why it was needed the first time, but why the
second time? The only reason I could give myself was that it was to test the
toolchain: if it can rebuild itself, it can build all other packages.

After finally figuring out what bootstrapping is (with input from a nice
forum thread in the "Gentoo Chat" department, information gathered from the
GCC mailinglist and some dev prodding online) I am now trying to work out a
reasonable scenario as to why someone would bootstrap his system as an
example for the guide.

You might be wondering why I didn't first write the damn guide and /then/
update the Gentoo Handbook. Two reasons are behind this. First, the Gentoo
Release Engineering project has asked me to do so, and they were kind enough
to give reasons (like bugreports, but also the theoretical problem with the
bootstrapping/system stuff, circular dependency stuff, etc.). The
installation instructions and the release engineering project are two hands
that should always work together and any discrepancy between them would lead
to confusion of the user.

The second one is my personal motivation: I want to be certain that users
/comprehend/ what they are doing rather than blindly copying over
instructions from one screen to another. We've had (and still have) lots of
users break their initial installation because they "forgot" to edit their
/etc/fstab. For a documentation writer, this is unacceptable. Any failed
installation is seen by me as either a (1.) very stupid user, or (2.)
failure on my part to document the instructions well.

This is my motivation, and this motivation is mine. 

Sincerely,

      Sven Vermeulen

-- 
  Gentoo Foundation Trustee          |  http://foundation.gentoo.org
  Gentoo Documentation Project Lead  |  http://www.gentoo.org/proj/en/gdp
  Gentoo Council Member  

  The Gentoo Project   <<< http://www.gentoo.org >>>