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 |