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 <[EMAIL PROTECTED]>. 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 [EMAIL PROTECTED] 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 <[EMAIL PROTECTED]> 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
