Re: concerning debian-reference and the necessity for the competitors
Hi, (I CCed folks affected by the Adam's posting in debian-doc, if you
are subscribed, please tell us so.)
On Tue, Feb 25, 2003 at 01:48:09PM -0600, Adam DiCarlo wrote:
> I would suggest we either kill or take steps to kill a number of
> unmaintained manuals.
I can not agree more. It was discussed back about a years ago. Back
then, we (or more appropriately, Josip) took a lead to change web page
arrangement to hide those unmaintained ones deep into the web page :-)
> I'm starting with manuals which are obsoleted, I suspect, by
> debian-reference, which seems like the flag-bearer right now for
> user/sysadmin information.
Thank you.
Before I start, Let me confirm that I did contacted some of
the authors with unfinished contents to work together. I think the
failure of the unfinished documents comes from the approach they took.
Since making reference is very elaborate works and it is very difficult
to be up-to-date, I decided early day that my "reference" that I will
not be too verbose. (I admit my lack of English skill and computer skill
was another reason.) It is best to give pointers to each package's
essential documents so people will be current even before I notice
package changes. Debian is quite dynamic target to document as a
volunteer work. Also there are many good guides in TLDP HOWTOs of which
we do not need any duplicated efforts.
In this sense, initial attempts by the DDP folks were aiming at more
comprehensive guide and style are quite different. I do not mind
merging few useful parts from any of the documents but I do not want to
end up a huge document I can not maintain.
> I know I am not being diplomatic and "correct" here -- but it's worse
> to have a DDP area which is mostly a graveyard of dead manuals. I
> feel it's better to have one maintained manual that 4 unmaintained
> manuals.
I could sense it from the tone of your previous mail.
I did not know which 5 you were talking about. There are 13 published
good Users' manuals in some shape and I know one (hands-on) in CVS.
We have seen few postings here such as "Debian packaging tutorial" by
Szabo Peter <pts@inf.bme.hu>. Problem is most of those are personal
memos which author are unlikely to **maintain** them.
http://www.debian.org/doc/ddp needs to give guidance to these prospectus
contributors. Some ROADMAP for improving existing manuals needs to be
there.
Also I think defining and posting
1. Focus subject and scope limitation
2. Focus audience and assumed skill level
3. Update situation (active, frozen, old, stalled, ...)
should make it easy for new contributor to decide. (I think current
description on web pages are mostly good but consistent style is always
good idea. If you have any suggestion.)
As I see, http://www.debian.org/doc/topics seems totally outdated too.
Anyway let's review situation.
Usable manuals specific to Debian (w.d.o/doc/ page)
Users' manuals
* [1]Debian GNU/Linux FAQ
* [2]Debian Installation Manual
* [3]Debian Release Notes
* [4]Debian Reference (General Tips)
* [5]APT HOWTO (Single topic guide)
* [6]dselect Documentation for Beginners (Do we need aptitude guide?)
* [7]User's Guide (This needs to be updated
to be a Sarge Installation
Manual.)
* [8]Debian Guide (General install, old)
* [9]The Debian Linux User's Guide (General install.
More like contrib to
DDP. not in SGML)
* [10]Euro support in Debian GNU/Linux (Single topic guide)
* [11]Debian GNU/Linux and Java FAQ (Single topic guide)
* [12]Securing Debian Manual (Good focus issue guide)
* [13]The Linux Cookbook (General Tips.
More like contrib to
DDP. not in SGML)
I think 1, 2, and 3 has been the core of the Debian specific system
documents so you may consider the rest of 10 (+1) being miscellaneous
documents.
These all can stay for now. (Progeny one may go eventually by getting
absorbed...)
As for obsolete and sad shape documents. (w.d.o/doc/ddp page)
* Debian META Manual, incomplete and outdated, dubious purpose given
these web pages
* Debian Tutorial, obsoleted by Debian Guide
* Debian User Reference Manual, stalled and quite incomplete
* Debian System Administrator's Manual, stalled, almost empty
* Debian Network Administrator's Manual, stalled, incomplete
* How Software Producers can distribute their products directly in .deb
format, merely planned
* Debian Packaging Manual, partly merged in Debian Policy Manual, the
rest will be included in a dpkg reference manual that is yet to be
written
* Introduction: Making a Debian Package, obsoleted by Debian New
Maintainers' Guide
* Debian Programmers' Manual, obsoleted by Debian New Maintainers' Guide
* Debian Book Suggestions, merely planned, see the books page
* Debian Dictionary, planned
(This is longer list than Adam's one)
> So -- I don't mean to disrespect anyone's efforts. I'd just like to
> clean up some dead stuff which is unmaintained and focus our efforts
> in a single place. My interests are in better docs for our users, a
> sustainable DDP, and a clear place to go for contributors, translators, etc.
^^^^^^^^^^^__ This is tough one
I think each manual has to be at least 50 pages in A4/Letter print out.
I also think each manual has to be less than 300 pages to be
maintainable. Debian Reference is about 200 pages.
> Below I list a number of manuals which may or may not candidates for
> merging into debian-reference and then eliminating. Please do shout
> out loudly if one of the following manuals should *not* be so
> integrated for some reason.
> * tutorial
"Debian Tutorial"
> Pretty clearly obsolete and no longer maintained. Suggest we review
> it for anything that might be sensibly added to debian-reference and
> then 'cvs rm' it.
I agree it is obsolete but may worth keep it as a historical document
for now. Good general contents. hands-on (doocbook-sgml), or
users-guide overlaps this too. Writing style and focus audience is
different, though.
I do not mind merging some contents. But if we make debian-reference to
be any fatter on typical newbie general unix thing which most debian
user do not need to read, sustainability and translation will suffer.
> * user
You mean "Debian User Reference Manual"
> Most of it is just outline/draft. Suggest we review it for anything
> that might be sensibly added to debian-reference and then 'cvs rm' it.
Installmanual and (Progeny) User's Guide fills this in. Hands-on is also
better than this. If Ardo agrees, we should stop publishing and put into
CVS/Attic.
> * debian-guide (package, not in CVS)
"Debian GNU/Linux: Guide to Installation and Usage"
> Unmaintained, is seems to overlap with debian-reference, does it have
> anything to offer not in that document?
This was for potato and essentially alternative install-guide with some
user reference. Since John is active developer, I CC this message to
John.
Nice style for Unix introduction. If it is to be merged, it should be
installmanual or hands-on type documents. I say keep it for now.
> * system-administrator
>
> Seems to overlap with debian-reference, only had two content commits
> in 2002, and only a translation was adding all of 2001. Probably has
> some contents which could be integrated in debian-reference.
The current maintainer (Tapio Lehtonen) wishes to keep it and want to
grow document by the contribution from others. My observation is that
it has not work yet. He is DD.
I also invited him to work together into "Debian Reference" long time
ago. He was not interested and wanted to keep working on his documents.
That is my side of story.
Can we hear from you, Tapio?
> * network-administrator
> Only two content commits in 2002, one in 2001, 2 in 2000. Suggest we
> see if rkrusty is amenable to working with debian-reference instead.
Some good contents exist in it but quite verbose. Many tutorial things
overlaps with TLDP HOWTOs. I think Debian Reference needs some short
but nice networking intro addition. I do not think Ardo has any issue
removing this as long as some of the existing subjects are covered
elsewhere.
Wait, it is now updated by rkrusty@debian.org. He is doing this without
even adding him to CVSROOT/users. This is new thing I did not catch.
So Russian translator is starting new page? Interesting.
Ivan E. Moore (rkrusty), can you tell us your intent?
* users-guide (You missed this, the Progeny one, this CVS was created by
me.)
This is there as a interim measure. Until there will be next super sold
Sarge installmanual by Chris, this is here. He did already took many
parts from this document to Woody installmanual.
Anyway, maintaining user manual by one person which stretch this scope is
coming to my limit.
I do agree we need some direction.
So much for now.... (Sorry, I need to have been shorter.)
--
~\^o^/~~~ ~\^.^/~~~ ~\^*^/~~~ ~\^_^/~~~ ~\^+^/~~~ ~\^:^/~~~ ~\^v^/~~~ +++++
Osamu Aoki <osamu@debian.org> Cupertino CA USA, GPG-key: A8061F32
.''`. Debian Reference: post-installation user's guide for non-developers
: :' : http://qref.sf.net and http://people.debian.org/~osamu
`. `' "Our Priorities are Our Users and Free Software" --- Social Contract
Reply to: