[tale: Re: Notes for DDP writers]
----- Forwarded message from Tapio Lehtonen <tale> -----
Date: Sun, 14 Feb 1999 09:45:23 +0200
From: Tapio Lehtonen <tale>
To: Adam Di Carlo <aph@debian.org>
Subject: Re: Notes for DDP writers
X-Mailer: Mutt 0.95.1i
In-Reply-To: <[🔎] oaww1llfg9.fsf@burrito.fake>; from Adam Di Carlo on Sun, Feb 14, 1999 at 12:30:46AM -0500
On Sun, Feb 14, 1999 at 12:30:46AM -0500, Adam Di Carlo wrote:
> 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.
I did not know there was a tool in Debian GNU/Linux to produce PDF. I
agree PDF is preferable to PS in this case.
>
> > 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.
>
The write should use the same tag for the same purpose consistently,
then it is possible to automatically convert it to the corresponding
Docbook or whatever tag. Otherwise a person has to do this conversion
manually. I'm not claiming that it is possible to do the conversion
fully automatically, but it helps to have at least some parts of it
done for you.
> > 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.
>
I think I misunderstand the above statement. It seems to say, that you
would like to remove the Debian Documentation Project 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.
>
Well, at least the Debian Documentation Project manuals are supposed
to be Debian manuals. I agree that most of the things in them would
apply to other Unix systems also, but I do not see any problem in this
(and if it is a problem, the only way for us to solve it would be to
start developing Debian on a tangent to the other Unixes, to
eventually reach a point where anything that works in Debian is sure
not to work anywhere else. But I digress).
When the Debian manuals start talking specific things and examples,
they are very Debian centered. If we were to remove from the manuals
the general parts that apply to a generic Unix system, we would get a
short and consice manual, but it would probably not be very readable
or even useful for beginners.
>
> > 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.
>
That is the reason the question makes sense. If there are many GUIs,
it is reasonable to ask if there is one that is the standard GUI. And
the context implies, that if there is a standard GUI, then it would be
reasonable to write a tutorial on how to use it for beginners.
> > 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.
>
In my opinion, the above is an unnecessary vitriolic comment. Surely
this is a forum for discussing things, and not for flaming those who
see things a little differently. And I really think that a tutorial on
using the GUI is needed, after all, the Desktop is where Linux is
'considered' inferior to that other system. Personally, I find Linux
is technically superior, but for the majority of people to agree with
this it would help to have clear and easily readable documents when
they start using Linux.
> --
> .....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>
>
>
> --
> To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
> with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
>
--
Tapio Lehtonen
Tapio.Lehtonen@IKI.FI
----- End forwarded message -----
--
Tapio Lehtonen
Tapio.Lehtonen@IKI.FI
Reply to: