On Fri, 12 Feb 1999 09:35:30 +0200, Tapio Lehtonen <[EMAIL PROTECTED]> said: > Hello documentation writers. I have now found some time to devote to > the documentatation project, here are some results for discussion > and comments.
I applaud your sentiments but I'm afraid I disagree on most salient points you raise. > I also read some documents, and noticed the makefiles do not have a > PostScipt target. I propose this is added to all manuals, and the > manual maintainer checks the postscript version compiles. When I > have to read through the whole manual, I much rather print it on > paper and read from there. This way it is also easy to make notes. PostScript is inherently resolution dependant and non-portable. I suggest PDF, which is smaller and more likely to be viewable by all. > Use tags wisely, so that automatic conversion to Docbook would be > possible. I still hope manuals are converted to Docbook some day in > the future. Let us try not to paint ourselves in to a corner. Of > course, it may just be that I'm so used to writing in DocBook that I > am annoyed about those things I can not do in Debiandoc. Yes, I agree with you, but I would point out that automatic conversion to docbook is a problem of SMGL transformation; there's little a writer could do to make it easier or harder. > There seems to be a lot of overlap between documents, the same > concepts are discussed in two or more manuals. I was going to write > about filesystems in "System Administrator's Manual", but this is > already in "Debian Tutorial" and in "User Rererence Manual". I'm not > sure I can add anything meaningful to what is already written. I'm sorry, but I'm going to have to *strenuously object* to the mere existance of these manuals. For one, 90% of the contents of these manuals are Linux-specific and not Debian specific. As such, to undertake these manuals as *Debian* manuals is contrary to the ideals of the Free Software Movement -- sharing and the greatest benefit to all. I happen to know a *number* of quality Linux documentation folks who have taken issue (quietly) with the existance of these manuals. I really think this is important. Debian manuals should be about Debian. Linux manuals should be worked on by groups which are not just restricted to the Debian group. > This leads to two issues: we should coordinate what is written to > which manual, and get links between manuals. Now it is possible to > use cross references within a document, but to get links to other > DDP manuals we should either agree to use the url -tag, or get a new > tag for this. If we use the url -tag, we may have to assume the > manuals are in a certain place, perhaps a relative reference. I think relative URLs between manuals should be avoided. It assumes that certain packages are installed (i.e., for local browsing). I think for now we need to establish well-known locations for all of these packages. The Debian webmasters are *still* looking for volunteers on the www.debian.org documentation area, someone from this group. Anyone volunteer? > There seems to be very little in Tutorial and User Reference about > using a GUI. This may be partly because Debian does not have a > standard GUI (or does it?), I'm not sure this question even makes sense. Debian, and Linux, and GNU, and Unix in general, are GUI agnostic. There are *many* GUIs. > and partly because document writers are > advanced Unix users who do not consider using X Window an issue. If > GNOME becomes standard GUI, we should add a tutorial on setting it > up and basic usage. As a first step, links to the existing GNOME > documentation could be added to Debian Tutorial (and/or User > Reference). It is so absurd and upsetting to me to hear talk about this group, which is already so overworked and understaffed, to try to go about and document this stuff. -- .....Adam Di [EMAIL PROTECTED]<URL:http://www.onShore.com/>
