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