Re: [gentoo-doc] Regarding handbook/draft/complete

[Josh]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

This sounds intriguing. Certainly wireless networking and nVidia graphics cards
will still be around; I'll look into contributing something in those areas, as
they have always fascinated me (and sometimes been informative, aggravating
tasks to properly set up!). Best of luck, and thanks for the great material so
far. :)

PS: Though the very idea of an "in-print" Gentoo book is in many ways absurd, as
Gentoo is unique among Linux distros for its generally faster-paced, evolving
nature, these draft handbooks present the best possible approach to actually
publishing a "dead tree" Gentoo guide--something that would be a first for the
distro, AFAIK. Given Gentoo's rapidly changing nature (e.g. fundamental pieces
like Portage and baselayout), the need for a paper Gentoo book might seem
obviated. But I'm strangely attracted to the idea. It seems more doable now that
the draft handbooks have less of a specific Gentoo emphasis. I'd certainly be
interested in seeing Gentoo documentation in print!



Sven Vermeulen wrote:
> 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


-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.2 (GNU/Linux)
Comment: Using GnuPG with Thunderbird - http://enigmail.mozdev.org

iD8DBQFDzSOrrsJQqN81j74RAsieAKCfH4GHzO0jglwP4+2hVX9/Him4jgCfRUY9
ry31hhTsVkePUqy2LMAtzi0=
=PDsc
-----END PGP SIGNATURE-----
-- 
gentoo-doc@g.o mailing list