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
Message-Id: 725426.9250.qm@web31806.mail.mud.yahoo.com
In Reply to: Re: [gentoo-doc] Gentoo newbie ebook by Josh Saddler
1 Josh wrote:
2
3 > And, in my opinion, the guidexml handbook format for long documents
4 > works much better than a booklike format; it's superior to vanilla
5 > docbook as well -- another suggested format that comes up from time to time.
6
7
8 and Chris wrote:
9
10 >Keep in mind that we already have transformation scripts that we use for
11 >the Handbook during releases to convert the GuideXML into PDF. One of
12 >the advantages of GuideXML is the ability to transform it into other
13 >things quite simply.
14
15 As long as the format that the materials are placed into supports line numbers
16 and images/diagrams, I will be happy.
17
18
19
20 Josh wrote:
21
22 > That being said, the question here is twofold: what would hosting your
23 > work in progress do for Gentoo, and what would Gentoo hosting it do for it?
24 >
25 > So far, I haven't come up with anything realistic for either. More
26 > documentation or not, I still don't think adding something designed for
27 > utter computer/Linux newbies would be of any help. One thing I heard
28 > some other Gentoo devs mention the other day was that most of the
29 > frustrations of new users (Gentoo users were the subject here, but I
30 > think you can extrapolate this and apply it to Linux users in general)
31 > are caused by a common mindset: they simply aren't accustomed to the
32 > idea of reading in general. They *especially* aren't used to the idea
33 > that they have to read technical documentation.
34
35 I definitely agree that the problem of people not being accustomed to reading
36 is widespread.
37
38 However, after guiding numerous freshman classes through installing Gentoo
39 using the Gentoo Handbook, I have come to the conclusion that most of the
40 frustrations that these students experience are due to the Handbook not being
41 designed specifically for newbies ( and I think the Handbook is excellent at
42 what it is designed for, BTW ).
43
44 The reason I think this is because I am in the computer laboratory during the
45 installation process and I get to observe newbies working through the Handbook
46 step by step. I know everyone is reading the materials because I am constantly
47 running around the room, looking over everyone's shoulders and helping them
48 with their difficulties :-)
49
50 I have been teaching this class for about 3 years now and this has given me the
51 opportunity to see person after person encounter the same difficulties at the
52 same points in the Handbook. Over time, I found myself giving each student
53 that encountered a given difficulty a standard explanation which was helpful
54 for overcoming it. A significant portion of the gentoo_linux_install document I
55 have created consists of covering the same information that the beginning part
56 of the Handbook does, but at a much slower pace and with all of the difficult
57 parts I am currently aware of explained more fully.
58
59 Now, to address the questions in your first sentence. I am currently using the
60 materials in week 4 of a 10 week class and so they will be finished 6 weeks
61 from now ( unless I get hit by a truck or something :-) The size of the
62 overall document is at 135 pages now and I am projecting that the final
63 document will be between 175 and 200 pages. I am not proposing doing anything
64 with the materials until they are complete, other than having people here look
65 at them.
66
67
68
69 >What could the materials do for Gentoo?
70
71 - Cutting Gentoo's newbie frustration problem by perhaps 50%.
72
73 - Attracting a significant number of promising 13-20 year olds newbies to the
74 Gentoo site so that they can obtain fundamental computing knowledge which is
75 difficult to obtain elsewhere. If they are successfully able to finish the
76 materials, many of them will probably go on to become Gentoo users and perhaps
77 even developers.
78
79 - If the materials are used to periodically teach a free online class ( and I
80 will volunteer to teach it ), this would provide the opportunity to develop
81 news releases ( and perhaps articles ) which explain what the goal of the class
82 is, why it is unique and why Gentoo was the distro it was based upon. The
83 online class should provide different enough news content to attract the
84 interest of people who might not otherwise have considered looking at Gentoo.
85
86 I have more reasons I could list, but I think this is enough for now.
87
88
89
90 >What would Gentoo hosting it do for it?
91
92 My goal for the materials is to have them help as many frustrated computer
93 newbies as possible. I have taught free online classes in the past on more
94 specialized topics with class sizes up to 400. If marketed properly, Gentoo
95 classes based on these materials should have the potential to achieve class
96 sizes of 1000+. Having the materials eventually hosted by Gentoo would allow
97 them to benefit more easily from Gentoo's existing marketing capabilities.
98
99 Beyond this, Gentoo technologies are intimately woven into the fabric of these
100 materials and so I think they should be housed in a place where Gentoo
101 developers have easy access to them.
102
103
104
105 > You're going to need some extremely convincing arguments in favor of
106 > it before I, personally, will be sold
107 > on the idea.
108
109 Instead of trying too much harder to convince you, what I would like is the
110 opportunity to show you. What I have in mind is testing this idea by running a
111 small scale experimental newbie's class using the materials. I am not sure of
112 the best way to recruit newbies for the course, but perhaps locating people (
113 like Duncan's young friend ) through word of mouth would be sufficient.
114
115 Some members of the Gentoo Documentation Project could then monitor the course
116 and determine whether it is worth pursuing further after it is completed.
117
118
119 Respectfully,
120
121 Ted
122 tkosan@×××××.com
123
124
125 --
126 gentoo-doc@g.o mailing list

Replies

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