Re: Notes for DDP writers
On Fri, 12 Feb 1999 09:35:30 +0200, Tapio Lehtonen <email@example.com> 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
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 Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>