[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

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: