Notes for DDP writers
Hello documentation writers. I have now found some time to devote to
the documentatation project, here are some results for discussion and
comments.
The Debian dictionary should be used. To achieve consistent usage of
terminology, we should add all terms to the dictionary and then look
them up before using. This way DDP manuals do not confuse the reader
by using the same term meaning different things in two manuals or even
within the same manual.
I added two terms to the dictionary (filename, pathname), but I'm not
sure if the tags I used are best possible. The "taglist" looks
reasonable, but then I can not get cross references.
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.
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.
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.
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.
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?), 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).
Summary:
- Add all terms used to the Debian dictionary
- Postscript target to all makefiles
- Add using GUI to Tutorial
--
Tapio Lehtonen
Tapio.Lehtonen@IKI.FI
Reply to: