Gentoo Archives: gentoo-doc

From: Sven Vermeulen <svermeulen@××××××.be>
To: gentoo-doc@l.g.o
Subject: [gentoo-doc] Regarding handbook/draft/complete
Date: Tue, 17 Jan 2006 08:18:33
Message-Id: 40548.193.244.32.140.1137485847.squirrel@193.244.32.140
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

Replies

Subject Author
Re: [gentoo-doc] Regarding handbook/draft/complete Josh <jackdark@×××××.com>