Gentoo install documetation; time for a facelift

LJ · Apprentice Joined: 27 Dec 2002 Posts: 156

I've been using Gentoo for a year now and, for many purposes, it's hands down the best distro available. I'm even running an official source and rsync mirror.

The reason for this is many-fold: the community goes out of its way to help people get their Gentoo systems up and running and continues to help all users as much as they need. Gentoo has an exceptional package management system and the documentation, for the most part, far exceeds the necessity. Unfortunately, a weakness in Gentoo's documentation has emerged (no pun intended) since I first installed.

Back then, the documentation had a couple forward references but most users could follow it sufficiently well. A few things weren't explained clearly enough however, and people who failed the install process may never have figured out why. Recent additions, especially the GRP install instructions, have caused far too many unclear forward references in the documentation. The documentation may seem clear to those who wrote it and those deal with it on a very regular basis but I assure you, it is not clear to those who matter most if Gentoo wishes to sustain the growth it has been enjoying. I often encourage people to install Gentoo and observe them questioning the current documentation at some points or find that they've failed because the documentation lacks clarity. The forward references create a problem that is exasperated by the general wordiness.

My proposal is simple: maintain several copies of the install documentation. There should be a specific document that tells you how to install Gentoo using GRP and nothing else; another one that explains how to do it from stage1, another from stage2, and yet another for installation from stage3. The explanation of the documentation should also be pulled out and exist as a separate document.

Forward references in documentation are acceptable if you're printing out a manual with very limited space and it has to fulfill the needs of everyone who buys your product. However, they're not acceptable here; having a few more digital copies sitting on a web server costs next to nothing. Putting those documents on the install CDs costs nothing. Conversely, Turning off prospective users because of sloppy install documentation is costly.

Helena · Posted: Fri Oct 31, 2003 7:31 am Post subject:

I completely agree, in every respect. Gentoo is top-class and also fun! I must add that it is the distribution which finally made me step into the Linux world.

The documentation, as you say, is indeed not up to standard, it is perhaps too much written from a technical viewpoint. Another way to improve readability would be to move certain material to appendices, e.g. the detailed pages about partitioning. If necessary, I can put out some further suggestions.

I would also add that printing the documentation sometimes is a hassle. Although the new XML style and the option ?style=printable suggest otherwise, I seem to have consistent trouble fitting the documentation on a standard A4 page. I print from a Windows machine, true, but I've tried both Internet Explorer and Mozilla, and both are not completely satisfactory.

pietro-ki

Me too, I agree, doc in pdf format is OK (IMHO), it's impossible break it,
but HTML format can be easily broken into few pages, linked together.

So one can follow main stream without many tech details and another one
can read all tech appendicies if they want to.

I tryied to install last version (zlib error) and I did it for x times. Browsing
one huge page install.html for n-th time is frustrating.

Well, I can and I want to help ("Don't ask what your country can do for you, ...")
where and how I can upload splitted version of install.html?

Have a nice day!
Pietro

P.S. another little oops: there is install.html file on Live CD, but
w/o immages (no space on CD??) I know, for direct browsing with
links immages aren't needed, but if one want browse install.html
on another sistem (for curiosity only) ?
_________________
Have a nice day !

Pluvius · Posted: Fri Oct 31, 2003 4:50 pm Post subject:

I agree. I would like to see separate install guides for stage 1, 2, 3 and GRP. I'm still a n00b, but I could probably noodle them together with someone else checking my output before they become official guides.

I've really enjoyed the experience building my Gentoo box from stage 1 back in the 1.1 days and all the help I got from reading the forums. I would like to help by giving something back to gentoo in return.

However, simplifying the installation instructions will open gentoo up to people that may not be ready for the experience. It true that gentoo appears to be getting easier, but I might caution that not everyone will be ready to buid their own kernel.

Pluvius

Earthwings · Posted: Fri Oct 31, 2003 5:26 pm Post subject:

People are working on it. Some of the things you are mentioning are going to be implemented soon. See http://www.gentoo.org/proj/en/glep/glep-0013.html