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@gentoo.org mailing list
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@gentoo.org mailing list
