[gentoo-doc] DRobbins 2007.0 review

[Duncan]

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^)

-- 
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