1 |
Hi all, |
2 |
|
3 |
Some of you might have noticed that I committed a lot of new files in the |
4 |
CVS repo under [gentoo]/xml/htdocs/doc/en/handbook/draft/complete. What |
5 |
you see there is an idea I had regarding the/a Gentoo Handbook which |
6 |
focusses on something entirely different from our current Gentoo Handbook. |
7 |
|
8 |
Currently, the Gentoo Handbook is meant to provide Gentoo-specific, static |
9 |
information to the end user. Such information, like the installation |
10 |
instructions, Portage stuff, init scripts, ... is not interesting for |
11 |
non-Gentoo users. Even more, Gentoo users only have "limited" need of this |
12 |
document: it only contains the Gentoo-specific aspects. |
13 |
|
14 |
That isn't a bad thing. It keeps the documentation coherent and easier to |
15 |
maintain, something we noticed over the last few months where handbook |
16 |
changes have become less and less frequent. However, many users are |
17 |
missing a Gentoo-centered Linux-general document. |
18 |
|
19 |
This is what the new draft attempts to become: a full handbook covering |
20 |
various technologies that Linux (the operating system) offers to its |
21 |
users, using Gentoo Linux as the glue to help users install and maintain |
22 |
their system. |
23 |
|
24 |
As such a handbook is dangerous to develop (as many technologies grow and |
25 |
develop over months while writing such a handbook takes at least another |
26 |
year), the style in which the handbook is written should be more |
27 |
explanatory and less tutorial-based. This means that the step-by-step |
28 |
examples should be minimized, but that the technologies behind it should |
29 |
be clearly documented and well explained. |
30 |
|
31 |
The current draft is not finished, only one-and-a-half part is filled in |
32 |
and many will follow. I want to ask all of you to take a look and state |
33 |
your opinions on it. I also want you to help out writing this book: if you |
34 |
know any interesting technologies that will remain apparent in the Linux |
35 |
OS even in one year, do write on it. |
36 |
|
37 |
Personally, I think that I'll first write separate guides on the subjects |
38 |
(which will be step-by-step) after which I create a chapter in the |
39 |
handbook that covers the technology without going too deeply in the |
40 |
step-by-step instructions. |
41 |
|
42 |
I want this to be clear: the handbook should *not* cover the commands in |
43 |
great detail but rather help the reader find out what is possible with |
44 |
Linux, understand the technology and be able to search for the specific |
45 |
documentation on the Internet. |
46 |
|
47 |
For instance, the LVM2 documentation in the handbook should cover the |
48 |
essentials of LVM2: the logical, abstract idea behind it (separation of |
49 |
physical versus logical), features (like snapshotting) with examples how |
50 |
easy it is to create such setups (yes, examples are important) but not |
51 |
with a complete white paper on a specific setup. Difficult topics that are |
52 |
well documented elsewhere should be mentioned but not copied (think LVM2 |
53 |
for root file system). |
54 |
|
55 |
My asbestos suit is in place, my fingers are well protected with hardened |
56 |
steel gloves to counter Yoswink's knife and I have my cookies at hand to |
57 |
get enough sugar to survive this thread. |
58 |
|
59 |
Wkr, |
60 |
Sven Vermeulen |
61 |
-- |
62 |
gentoo-doc@g.o mailing list |