Gentoo Archives: gentoo-doc

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