[gentoo-dev] Concerns about the new install guide

[Brad Laue]

Hi all,

I have a few concerns about the new install-guide. The documentation 
within it is quite complete, and is able to guide a user from the 
beginning to the end of an install of Gentoo, but it's getting out of hand.

When I began using Gentoo there was a 12 page long text file which 
detailed the steps to take and a few alternatives. Compressed, and 
without verbiate description, the entire guide was able to be shrunk 
down to about a page and a half (on x86 CD's, for 1.2).

The original guides, the text files, gave someone a feel for the install 
itself, as in the basic steps. Network config, partition, format, unzip 
a stage, copy resolv.conf, chroot, sync, bootstrap, system, 
kernel/syslogd/cron, lilo.conf, fstab, done.

I'm concerned that the new guide, which covers not only x86 but all 
architectures in a massive document is not going to be helpful for a 
relatively new user who just wants to get it installed on their PowerMac 
or their new Pentium 4. Commentary is a good thing, and inclusion of 
instructions for all architectures is slick, but I think it needs to be 
moderated slightly.

For example, clever use of XML can allow us to write an entire 
installation guide for all architectures in one common base of 
documents, and then can allow us to selectively generate a guide for x86 
or SPARC on the fly. This would keep maintenance hassle to the same 
minimum it's at now, and would make installation instructions much 
clearer for the new reader (instead of reading and skipping, reading and 
skipping, and hoping he/she hasn't gone too far).

More than anything else, one has to figure out for ones self what the 
basic steps (outlined above) for installing Gentoo are; while this seems 
a minor thing, it's one of the aspects of the original Gentoo 
installation guide which struck me the most. After my first install I 
knew all the steps, and hardly had to refer back to the installation 
guide for coaching. I doubt that if I started out now, I'd get such a 
clear idea of what's required after my first read-through of the guide.

Finally, I think the multi-page version is a good document to keep 
around. It's great on the website as it expands upon the installation 
process and how it works, and what's good/bad about various options, 
which keeps people informed. But at the very least, is it possible to 
consider placing a condensed set of installation instructions similar to 
those  present back in the day of 1.2 on the CD's themselves?

Brad

--
gentoo-dev@g.o mailing list