[gentoo-doc] Re: DRobbins 2007.0 review

[Duncan]

Chris Gianelloni <wolf31o2@g.o> posted
1180737662.17690.94.camel@×××××××××××××.com, excerpted below, on  Fri, 01
Jun 2007 15:41:02 -0700:

> Why not just rename the "2007.0 Handbook" into the "2007.0 Networkless
> Installation Guide" or something similar?  After all, the versioned
> Handbooks are only good for the release they correspond to and it won't
> mean going back to having a single and confusing Handbook.  All that is
> really needed is a link to the networkless guide for people to follow if
> they're planning on a networkless install, assuming it isn't there
> already.

Renaming, so there's just one "Handbook", would indeed help.

What I'm left wondering, however, is why this:

http://www.gentoo.org/doc/en/handbook/2007.0/index.xml

(which /does/ say it's networkless only) then includes the non-
installation parts of the handbook, Working with Gentoo, Working with 
Portage, and Gentoo Network Configuration (on what's supposed to be for 
networkless?)?

If it's not intended to be the whole handbook, only the networkless 
installation guide, why does it /look/ like the whole handbook?

A second question is one raised in the DRobbins review, but now relating 
to documentation.  I still don't know which "handbook" he was following, 
but the installer CD he was using didn't have stages or sources.  The 
"Networkless"/dated "handbook"  talks about prebuilt packages on the CD, 
while the general handbook says two different things in different 
places.  In chapter 2, it explains that the minimal CD simply boots the 
system and prepares the network, where everything else comes from "live", 
while the Installer LiveCD contains everything needed to install Gentoo, 
networkless if needed/desired.  However, it then states that stage 
tarballs need to downloaded separately (how, if it's networkless), which 
would seem to make a lie of the "everything needed" claim.  If everything 
needed is included, a separate stage-X download is by definition NOT 
required, as it's "included" as part of "everything".  Chapter Five 
mentions a THIRD kind of CD, the "Universal" CD (Um... why wasn't this 
third choice mentioned earlier, in the section where people were actually 
supposed to be choosing install media?), which is said to include the 
stage tarballs, and thus would truly include "everything needed".  Again 
it says the other CDs, Minimal and LiveCD, don't include the necessary 
tarballs.  Again, how can the claim of "everything needed" /possibly/ be 
true, if the needed tarballs aren't included?

So which is it?  Does the LiveCD include "everything needed" as claimed, 
or does it require a NOT included stage tarball, as claimed elsewhere?

What it looks like to me is that the LiveCD installer is new and now 
emphasized on the media choices page of the main handbook, and in the 
networkless install (2007.0) "handbook", and the universal CD was 
possibly dropped, but general handbook chapter 5 wasn't updated to 
reflect the new situation.  Even when updated, however, there's still the 
issue of saying "everything needed" is included on the installer CD, when 
it apparently isn't, since according to both the main handbook and the 
DRobbins review, the stage tarball must be downloaded separately.  (His 
comment was that a fully functional GNOME including Evolution was on the 
CD, but not the stage tarball, which he thought would be a more sensible 
use of the space required for the GNOME install.  Perhaps an X installer, 
but something lighter than GNOME, so the stage tarball could be 
included.  The point I'm making, however, is that if an additional stage 
tarball is required, don't say "everything needed" is included, quite 
separate from whether the full GNOME environment including Evolution is a 
wise use of the space.)

So anyway, yes, renaming the networkless install to something other than 
"Handbook is certainly one good step, IMO, so there's only one 
"Handbook", but it's only one step.  Maybe kill the additional parts 
(Working with portage and etc) from what is now the Networkless Install 
guide, so that's /all/ it is, would seem wise to me also (tho there are 
arguments that could be made to keep them).  The above confusion over 
media and "everything needed" must be addressed too.

That would (IMO) straighten out the immediate confusion.  Beyond that, 
doing the single landing point for all things install documentation 
related I think is also a good thing, but not as vital, so even if 
undertaken, could be a longer term project.

-- 
Duncan - List replies preferred.   No HTML msgs.
"Every nonfree program has a lord, a master --
and if you use the program, he is your master."  Richard Stallman

-- 
gentoo-doc@g.o mailing list