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