sarge and the debian docs...
Posted: 2005-05-26 18:39
I've got a Gentoo home server I'm considering to upgrade to
Debian Sarge when released. Working with Gentoo had some
advantages but I find I am spending too much time cleaning up
after problems generated by updates, or broken packages.
It is like trying to plant a garden while someone else is running
around with a roto-tiller.
Debian may be better for this role, at this point, because it does have
a concept of different repositories, and so one can select
only security updates rather than all updates, which is
too frequently available from Gentoo.
Looking over the Debian Doc site, I miss some aspects of Gentoo.
The style of Gentoo's documentation was fantastic.
It used color for notes, etc. The content was great too - it included
all of the details, with examples.
The style of Debian documentation is very 1995ish. The number of
links that are relevant to end users and administrators, versus
Debian developers, is rather low. Within the documentation, I'm
seeing revision dates 3 years old, and broken links.
Take for example, this testing version of the release notes for 3.1:
http://www.debian.org/releases/testing/ ... #s-newinst
Note the links in section 2.2. The first link brings us to the 3.0
install manual, not 3.1. The second link is broken. I've emailed
the address at the page bottom about it.
Is this normal for there to be stuff half built in the docs, or is
it due to the transition phase of going to 3.1?
While I'm not a Linux newbie, I am going to need to consult the
Debian docs to find information on the Debian way of handling things.
Contrast these two resources between Gentoo and Debian:
Gentoo Kernel Upgrade Guide
http://www.gentoo.org/doc/en/kernel-upgrade.xml
Debian Compiling a New Kernel
http://www.debian.org/releases/testing/ ... 05.html.en
Gentoo does a number of things better in their documentation,
in my opinion:
1. Many links are provided to more related Gentoo documentation and
resources: picking a gentoo kernel source, the handbook, etc.
2. All Gentoo code examples are real samples, not just bogus filler as
Debian docs tend to use. Real examples help one determine what are
keywords and what are variables. One look at a value like
"linux-2.6.9-gentoo-r2" and I know it is a variable, not a keyword
like "oldconfig". In Debian documentation, a value of "kernel_image"
could be either since I'm not familiar with fakeroot.
3. What you are doing is explained in the case of Gentoo. For Debian,
for example, I'm wondering what the hell fakeroot is - perhaps
another bogus filler like "kernel_image".
4. More details, not just summary reference.
5. More recent revisions. The testing version of the Debian
documentation refers to the most recent kernel as 2.4.27.
I'm sure the Debian documentation is useful, but it is clearly
more useful to someone that already knows what the various
bits are referring to.
Debian Sarge when released. Working with Gentoo had some
advantages but I find I am spending too much time cleaning up
after problems generated by updates, or broken packages.
It is like trying to plant a garden while someone else is running
around with a roto-tiller.
Debian may be better for this role, at this point, because it does have
a concept of different repositories, and so one can select
only security updates rather than all updates, which is
too frequently available from Gentoo.
Looking over the Debian Doc site, I miss some aspects of Gentoo.
The style of Gentoo's documentation was fantastic.
It used color for notes, etc. The content was great too - it included
all of the details, with examples.
The style of Debian documentation is very 1995ish. The number of
links that are relevant to end users and administrators, versus
Debian developers, is rather low. Within the documentation, I'm
seeing revision dates 3 years old, and broken links.
Take for example, this testing version of the release notes for 3.1:
http://www.debian.org/releases/testing/ ... #s-newinst
Note the links in section 2.2. The first link brings us to the 3.0
install manual, not 3.1. The second link is broken. I've emailed
the address at the page bottom about it.
Is this normal for there to be stuff half built in the docs, or is
it due to the transition phase of going to 3.1?
While I'm not a Linux newbie, I am going to need to consult the
Debian docs to find information on the Debian way of handling things.
Contrast these two resources between Gentoo and Debian:
Gentoo Kernel Upgrade Guide
http://www.gentoo.org/doc/en/kernel-upgrade.xml
Debian Compiling a New Kernel
http://www.debian.org/releases/testing/ ... 05.html.en
Gentoo does a number of things better in their documentation,
in my opinion:
1. Many links are provided to more related Gentoo documentation and
resources: picking a gentoo kernel source, the handbook, etc.
2. All Gentoo code examples are real samples, not just bogus filler as
Debian docs tend to use. Real examples help one determine what are
keywords and what are variables. One look at a value like
"linux-2.6.9-gentoo-r2" and I know it is a variable, not a keyword
like "oldconfig". In Debian documentation, a value of "kernel_image"
could be either since I'm not familiar with fakeroot.
3. What you are doing is explained in the case of Gentoo. For Debian,
for example, I'm wondering what the hell fakeroot is - perhaps
another bogus filler like "kernel_image".
4. More details, not just summary reference.
5. More recent revisions. The testing version of the Debian
documentation refers to the most recent kernel as 2.4.27.
I'm sure the Debian documentation is useful, but it is clearly
more useful to someone that already knows what the various
bits are referring to.