Re: [gentoo-doc] DRobbins 2007.0 review

[Josh Saddler]

Duncan wrote:
> [much rambling]

> This is a followup from
> http://linux.slashdot.org/comments.pl?sid=236711&cid=19324981
> and (beware the wrap)
> http://www.funtoo.org/drobbins/blog/2007/05/gentoo-linux-20070-review-
> first.html
>
> Nightmorph mentioned posting comments in regard to the documentation
> angle here, so here I am.  I've been lurking and don't /think/ I'm
> rehashing old discussions, but if so, just tell me.  Anyway, repeating
> the comment I made in the link, so folks don't have to go read it of they
> don't want to...
>
> In trying to reply to the issues as I did, well, let's just say I'd have
> been confused trying to read the present install documentation as a
> Gentoo newbie (it was confusing enough as it was, knowing what was in the
> old handbook and trying to see if it was in the current one, then finding
> there was a 2007.0 one as well).  It can be sorted out, but it's not
> easy, and whats worse, with both a 2007.0 handbook, and a general Gentoo
> Linux handbook, if someone goes for help and refers or is referred to the
> handbook, it's quite possible the person wanting help and the person
> trying to help will each be reading different "handbooks", and not even
> realize it until much confusion has ensued.
>
> - For 2007.1, full integration of the old Gentoo Handbook into the new
> Gentoo 2007.x handbook should be complete, so there's only one "handbook"
> and people won't get confused.  It looks like it was already headed that
> way, but unfortunately hadn't been completed.  Probably trim the parts
> other than installation from the old one as they appear to be in the new
> one already, and retitle the remaining installation "Manual
> Installation", or "Installation without the installer" or something
> similar.
>
> - Modify the existing Installation Documentation listing
> ( http://www.gentoo.org/doc/en/index.xml?catid=install ) or create a new
> one suitable to be the primary installation documentation landing point.
> Off the top of my head, that means moving the Installation Related
> Resources up, eliminating or condensing and possibly moving to the bottom
> the intro and doc repository paragraphs.
>
> - Further modifying the Installation Docs listing, reorder the list so
> commonly needed resources are at the top.  Leave the handbook first (but
> as I said, make sure there's only one "handbook", or at least deprecate
> and move a second one down under "Other", if it continues to exist),
> followed by the quick-install guide, tips and tricks, and alternate
> install methods.  Only those four under the first/main header.
> Everything else under "Other Related".
>
> - Consider making all four entries in the main install section language/
> arch-landers of their own, much as the two handbooks are already
> handled.  Thus, the quick install guide link on the main lander will link
> a (generic) quick install guide lander, which would in turn have the
> existing x86, sparc, and gfbsd guides, among others.  The G/amd64 FAQ and
> chroot howtos, currently linked from the amd64 project, may be possible
> candidates for linking on the tips and tricks lander.  The LVM2, GRUB
> error collection, USB, and Bluetooth guides may fit here as well, as may
> the MIPS guide.  Of course, if this is done, the descriptions for quick
> install and tips on the main installation lander page would need expanded
> to mention them, as appropriate.
>
> - Gentoo 1.4 upgrade could probably by now be removed or moved to a
> "deprecated" lander.  The 2.6 kernel upgrading guide may need to hang
> around for awhile, but could be moved to either the deprecated lander
> with G/1.4 or an upgrade lander, with the Gentoo upgrading guide.
>
> - Other possible landers if an alternate organization is chosen might
> include hardware (bluetooth, USB, MIPS, etc) and system software landers
> (GRUB, kernel 2.6 upgrading and genkernel guides, etc).
>
> - Given the studies demonstrating a dramatic drop in usability and
> simplicity when the number of choices exceeds 4-7, (coincidentally or
> not, seven is said to be the number of "memory elements" an average
> person seems to be able to hold in active instant memory at once, before
> things start dropping out), if we could reduce the number of immediate
> choices on the main Installation Documentation lander page to seven or
> less, using secondary landers as suggested above, I believe it would
> dramatically increase the usability of such a lander page.  Thus, that'd
> be a worthwhile goal, IMO.
>
> After fixing up the main installation docs lander page:
>
> - In all installation documentation other than the single Installation
> Docs lander, replace the possibly many references to related install
> documents with a single (or single per chapter anyway, in the case of the
> old/manual method handbook, given the length) but likely higher
> prominence reference to the Install Docs main lander.  This will simplify
> wording in multiple resources, while pointing all readers at the single
> common installation docs landing point, with the benefits that brings in
> terms of consistent and maintainable documentation.
>
>
> If this is done, I believe it will make finding the proper documentation
> easier and less confusing, and therefore, with luck, will increase the
> number of folks reading it.  With the installer getting better, it's not
> like newbies necessarily /have/ to read it any more, to get a working
> install, but I believe we'll all be happier if people continue to read
> the docs anyway, and it follows that making that easier to do is a goal
> worth pursuing.  Hopefully, this proposal, or anyway the discussion that
> might follow telling me why it's not as great as I think it is (;.;)
> before getting any feedback, will advance that goal.
>
> Either way, if I may be of help... =8^)
>

The only thing Daniel has revealed in his brief review is that *he* is
too advanced for the long-format handbooks. All he needs is the quicker
checklist form of the handbooks (the existing quick install guides)
since he has the process more or less memorized. I've spoken with Daniel
about this a few times now on both his blog and on IRC. The GDP
disagrees with what he thinks needs to be done.

A new user, both new to installing Gentoo and new to Linux, needs the
longer format handbooks that we have now. The reason why those go into
their detail is that users *will need to know* some basic terminology
and linux commands. They won't know what the hell they're doing if they
follow a one-page guide and then reboot into their system. When they run
into trouble, they'll have no idea what phrases like "chroot the
tarball" and other jargon mean when they ask for help in the forums and
on IRC.

Dunno what the hell you're talking about by "integration", but I will
say this: users need the Portage handbooks and the ever-critical
networking handbook too. They aren't going away. The handbook structure
will stay as-is. Changing it will not help the most central problem
we're up against: that users simply *do not read* documents, period.
It's not in their nature. No amount of restructuring or other
handholding will change that for them; they have to take the plunge into
the technical world of Gentoo on their own.

The only thing that might be changed is the naming convention of the
networkless vs. networked handbooks. While messages about which one you
should read are everywhere, somehow users still manage to miss the right
one, either because PEBKAC or other reasons.