Scheduled Maintenance: We are aware of an issue with Google, AOL, and Yahoo services as email providers which are blocking new registrations. We are trying to fix the issue and we have several internal and external support tickets in process to resolve the issue. Please see: viewtopic.php?t=158230

 

 

 

sarge and the debian docs...

Here you can discuss every aspect of Debian. Note: not for support requests!
Post Reply
Message
Author
labrador
Posts: 13
Joined: 2005-05-21 03:22

sarge and the debian docs...

#1 Post by labrador »

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.

Jeroen
Debian Developer, Site Admin
Debian Developer, Site Admin
Posts: 483
Joined: 2004-04-06 18:19
Location: Utrecht, NL
Contact:

#2 Post by Jeroen »

The biggest problem in Debian is that while like all agree the documentation sucks (well, it does suck in quite a number of area's), nobody really is taking the effort to actually organise the documentation in some good way (there are attempts at it, but I guess either too few people, or it's maybe also too hard for documentation people to get involved).

What's needed is some group of people, at least partly debian developer, who really take up this task and set up some good documentation site, and most importantly, to actually create the infrastructure for that and ways to allow people to contribute and improve on it easily.

For who's intestested, http://lists.debian.org/debian-doc is the mailinglist to offer your help.

labrador
Posts: 13
Joined: 2005-05-21 03:22

thanks for the comments

#3 Post by labrador »

Thanks for the comments. I'm glad to see that you and the
guys on the Debian docs mailing list are in favour of
revising things. They also commented that there is
a lack of interest in contributors.

What I see is that the scope of Debian is so large that it
puts a strain on getting things done. Everything in documentation
has to be reflected on the multiple platforms, for 4 output formats,
and in 20 languages.

I won't be surprised if some people resist changing the "machine"
that generates this, but I'm suggesting it fall back to 2 formats
that are both HTML, like Gentoo does: one for print and one for
screen. I don't think documentation has to be available for
people who only have something like a teletype terminal.
In mean, sure, have man pages, but the stuff on the web site
should be focused on resolving for two output media: screen and
paper, and then stop. There is little advantage to producing
PS and PDF versions these days.

I'd like to investigate the development of an XSL transformation
from XML to HTML, as Gentoo does. I'll need to get up
to speed on some of that. I know SGML and basics of XML,
DTDs, etc, very well, but not this newish XSL and style sheet stuff.

User avatar
moonlight
Posts: 49
Joined: 2004-09-15 18:13
Location: Belgium
Contact:

#4 Post by moonlight »

Jeroen wrote:The biggest problem in Debian is that while like all agree the documentation sucks (well, it does suck in quite a number of area's), nobody really is taking the effort to actually organise the documentation in some good way (there are attempts at it, but I guess either too few people, or it's maybe also too hard for documentation people to get involved).

What's needed is some group of people, at least partly debian developer, who really take up this task and set up some good documentation site, and most importantly, to actually create the infrastructure for that and ways to allow people to contribute and improve on it easily.

For who's intestested, http://lists.debian.org/debian-doc is the mailinglist to offer your help.
Jeroen, I think you are completely right. From the number of posts you have dropped on this forum, I can see you are one of those people really willing to help others, really willing to make Debian a distro for lots of people.

Since you are a system admin of the forum, you are maybe the correct person to address this 'documentation issue' towards the right Debian responsibles, ... I have the feeling (see also my post on Debian Wiki : http://forums.debian.net/viewtopic.php?t=403&highlight= ) that if a modern and easy to use infrastructure would be put in place, a lot of people are willing to help in building up the documentation (for example a modern Debian Wiki , like is allready put in place on the Gentoo site).

Cheers, Moonlight

Jeroen
Debian Developer, Site Admin
Debian Developer, Site Admin
Posts: 483
Joined: 2004-04-06 18:19
Location: Utrecht, NL
Contact:

#5 Post by Jeroen »

Well, what it takes is someone to take up the task him/herself to go look for how to set up this infrastructure, and actually doing so too. debian-doc@lists.debian.org is the mailinglist to start with. If I were able to exactly pinpoint where to help etc, it wouldn't be needed anymore for someone, the whole problem is, nobody has simply taken the lead on this. Mail your intentions to -doc, and simply start doing stuff, start setting up infrastructure, after seeing what's currently in place.

As long as nobody really takes the lead on this, Debian's documentation will remain sub-par.

elgrande
Posts: 16
Joined: 2005-06-04 10:47

debian documentation

#6 Post by elgrande »

I have never read any debian documentation.
Okay maybe while googeling (to google sth. is now a official word in german language :? ).
Nevertheless I love debian. Thanks for the cools System and just improve it instead of writing docu. Means more fun 4 me and you...

User avatar
moonlight
Posts: 49
Joined: 2004-09-15 18:13
Location: Belgium
Contact:

#7 Post by moonlight »

Hi,

I am not going to start a debate about 'documentation or no documentation'.

I am happy for you, that you can do all the things you want without it, ... but you have to keep in mind that there are a lot of people on this planet, that would like to start with Debian, ... and who are looking for good documentation.

Cheers, Moonlight

elgrande
Posts: 16
Joined: 2005-06-04 10:47

linux

#8 Post by elgrande »

Don't get me wrong... Everyone using Debian or any other free OS makes me happy.
The point in my eyes is: If you really want to have fun using Debian, more than all you'll need some distro unspecific linux knowledge. I think there is quite a lot of good docu about this... (eg. O'Reilly & Co.)
I guess if you have some shell knowledge and a little bit knowledge of the linux system architecture, you will get it.
Anyhow, Debian with kernel 2.6 and the new installer isn't too hard anymore... :-)
But, why not... if there is a good nice2read doku, I'll have a look at it, too. (In train or something like that)
But: I wouldn't like to have to write it...

Peace, elgrande

dmartinsca
Posts: 30
Joined: 2006-01-08 23:15
Location: Ontario, Canada

#9 Post by dmartinsca »

I'm new to debian and the documentation was one of the first things i noticed. Like labrador, i think that the style gentoo uses for their documentation is excellent. I have been looking for something to contribute towards the open source community for a while now so if I decide to stick with debian I would be more than willing to offer help to the documentation side of things. I've made note of the mailing list and I will see what i can contribute once I find my way around

Has the documentation always been 'sub-par'?

dnusinow
Debian Developer
Debian Developer
Posts: 75
Joined: 2005-12-12 16:35

#10 Post by dnusinow »

More or less, sorta. There's an amazing wealth of documentation on a Debian system. Check out /usr/share/doc where every package puts its docs in a directory named after the package. That's my first stop whenever I have a question on how to configure something.

While they're much maligned, learning to read manpages is a critical UNIX skill. In Debian, every binary is supposed to have a manpage, or else it's a bug.

And of course, there's a wealth of information in the Debian bug tracking system and in the mailing list archives. Granted, these aren't tutorial-style documents, but they're a treasure trove of good information.

Anyway, I hope that helps. I know documentation is a problem (and a really difficult one to fix) so don't let me discourage you from contributing there! But even if it looks like there's no good docs, there's a lot out there when you learn where to look.
David Nusinow

Jeroen
Debian Developer, Site Admin
Debian Developer, Site Admin
Posts: 483
Joined: 2004-04-06 18:19
Location: Utrecht, NL
Contact:

#11 Post by Jeroen »

Yeah, the big issue with Debian docs is those overview docs, general docs for much encountered problems, and docs about how to find the right docs. Much information is available, as David said above, but it requires some knowledge to find it.

See also http://forums.debian.net/viewtopic.php?t=581

Contributing would be good, and the best thing would be for someone with a vision and view on how to improve the documentation unity and findability and implementing such vision...

jjmac
Posts: 384
Joined: 2005-12-28 23:34
Location: Australia

#12 Post by jjmac »

Howdy,

I haven't had time to read through all of this yet, but i noticed ...

labrador wrote:
>>
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.
>>


"examples" , thats the magic word. I'll have to have a closer look at gentoos documentation. I used to use bsd man pages at one time as their explanations/descriptions tended to be more complete than those in Linux. Just the switches were often different (grin).

The lack of examples though, i find that very irritating, as in, a picture can speak reams.

Some people are "verbal", others are more "visual", while others tend to be more "tactile". It would seem that the docs i read are written mostly for the more verbally orientated. Which denies all the possibilities of the others.

I also, don't believe that the dumbing down of docs helps at all, it only produces obscurity due to inadequate models being used.

What i wouldn't have done for a decent example file at times :), so much time would have saved.


jm

Post Reply