> And, in my opinion, the guidexml handbook format for long documents
> works much better than a booklike format; it's superior to vanilla
> docbook as well -- another suggested format that comes up from time to time.
and Chris wrote:
>Keep in mind that we already have transformation scripts that we use for
>the Handbook during releases to convert the GuideXML into PDF. One of
>the advantages of GuideXML is the ability to transform it into other
>things quite simply.
As long as the format that the materials are placed into supports line numbers
and images/diagrams, I will be happy.
> That being said, the question here is twofold: what would hosting your
> work in progress do for Gentoo, and what would Gentoo hosting it do for it?
> So far, I haven't come up with anything realistic for either. More
> documentation or not, I still don't think adding something designed for
> utter computer/Linux newbies would be of any help. One thing I heard
> some other Gentoo devs mention the other day was that most of the
> frustrations of new users (Gentoo users were the subject here, but I
> think you can extrapolate this and apply it to Linux users in general)
> are caused by a common mindset: they simply aren't accustomed to the
> idea of reading in general. They *especially* aren't used to the idea
> that they have to read technical documentation.
I definitely agree that the problem of people not being accustomed to reading
However, after guiding numerous freshman classes through installing Gentoo
using the Gentoo Handbook, I have come to the conclusion that most of the
frustrations that these students experience are due to the Handbook not being
designed specifically for newbies ( and I think the Handbook is excellent at
what it is designed for, BTW ).
The reason I think this is because I am in the computer laboratory during the
installation process and I get to observe newbies working through the Handbook
step by step. I know everyone is reading the materials because I am constantly
running around the room, looking over everyone's shoulders and helping them
with their difficulties :-)
I have been teaching this class for about 3 years now and this has given me the
opportunity to see person after person encounter the same difficulties at the
same points in the Handbook. Over time, I found myself giving each student
that encountered a given difficulty a standard explanation which was helpful
for overcoming it. A significant portion of the gentoo_linux_install document I
have created consists of covering the same information that the beginning part
of the Handbook does, but at a much slower pace and with all of the difficult
parts I am currently aware of explained more fully.
Now, to address the questions in your first sentence. I am currently using the
materials in week 4 of a 10 week class and so they will be finished 6 weeks
from now ( unless I get hit by a truck or something :-) The size of the
overall document is at 135 pages now and I am projecting that the final
document will be between 175 and 200 pages. I am not proposing doing anything
with the materials until they are complete, other than having people here look
>What could the materials do for Gentoo?
- Cutting Gentoo's newbie frustration problem by perhaps 50%.
- Attracting a significant number of promising 13-20 year olds newbies to the
Gentoo site so that they can obtain fundamental computing knowledge which is
difficult to obtain elsewhere. If they are successfully able to finish the
materials, many of them will probably go on to become Gentoo users and perhaps
- If the materials are used to periodically teach a free online class ( and I
will volunteer to teach it ), this would provide the opportunity to develop
news releases ( and perhaps articles ) which explain what the goal of the class
is, why it is unique and why Gentoo was the distro it was based upon. The
online class should provide different enough news content to attract the
interest of people who might not otherwise have considered looking at Gentoo.
I have more reasons I could list, but I think this is enough for now.
>What would Gentoo hosting it do for it?
My goal for the materials is to have them help as many frustrated computer
newbies as possible. I have taught free online classes in the past on more
specialized topics with class sizes up to 400. If marketed properly, Gentoo
classes based on these materials should have the potential to achieve class
sizes of 1000+. Having the materials eventually hosted by Gentoo would allow
them to benefit more easily from Gentoo's existing marketing capabilities.
Beyond this, Gentoo technologies are intimately woven into the fabric of these
materials and so I think they should be housed in a place where Gentoo
developers have easy access to them.
> You're going to need some extremely convincing arguments in favor of
> it before I, personally, will be sold
> on the idea.
Instead of trying too much harder to convince you, what I would like is the
opportunity to show you. What I have in mind is testing this idea by running a
small scale experimental newbie's class using the materials. I am not sure of
the best way to recruit newbies for the course, but perhaps locating people (
like Duncan's young friend ) through word of mouth would be sufficient.
Some members of the Gentoo Documentation Project could then monitor the course
and determine whether it is worth pursuing further after it is completed.
firstname.lastname@example.org mailing list