Gentoo Archives: gentoo-doc

From: Ted Kosan <tkosan@×××××.com>
To: gentoo-doc@l.g.o
Subject: Re: [gentoo-doc] Gentoo newbie ebook
Date: Wed, 31 Jan 2007 23:16:43
In Reply to: Re: [gentoo-doc] Gentoo newbie ebook by Josh Saddler
Josh wrote:

> 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. Josh wrote:
> 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 is widespread. 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 at them.
>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 even developers. - 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. Respectfully, Ted tkosan@×××××.com -- gentoo-doc@g.o mailing list


Subject Author
Re: [gentoo-doc] Gentoo newbie ebook Stephan Wehner <stephanwehner@×××××.com>