Ardo van Rangelrooij <ardo.van.rangelrooij@tip.nl> writes:
>
> robert havoc pennington <rhpennin@midway.uchicago.edu> writes:
>
> > On 16 Dec 1997, Ardo van Rangelrooij wrote:
> [snip]
> > > This also should make it feasible to have the tutorial ready when
> > > Debian 2.0 is released which will be early next year. I certainly
> > > don't intent to push us to have it ready at all cost, but it's a goal
> > > worthwhile striving for, I think.
> > That would be really nice. Perhaps we should make a timeline with
> > some sub-deadlines to keep ourselves on track? Or would that be too much
> > like work? ;)
> Well, what we at least could do is to say e.g. something like after
> then and then we only do proofreading and editing and no new material
> is being added, just as is done for Debian itself (more or less).
and a supposed deadline may help to give each author a feeling on when
a work should have been done. So we can indicate where we must help
each other to reach our goals.
> > What do we do first? Should we start writing up an outline?
> I indeed think this is the best way to go. We could take your "flow"
> as a starting point. Do you have any idea how many people would be
> needed to get this tutorial done? My guess would be 3 or 4 to keep
> things workable and communicatable. Especially since there's already
> some text written this should be feasible.
One important aspect is the internationalisation of our
documents. I've translated our installation manual into the german
language. The first translation is relatively easy. But it's a pain to
keep track on the changes in the original document. Therefor I suppose
a mechanism to move all important changes to each language version of
a specific document and leave the exact wording to the feeling of the
native speaker.
My idea is to maintain a skeleton which contain all the important
informations including figures and examples. This skeleton should be
part of every document. By comparing the skeletons we can find the
parts of a document that needs an update.
<------------------ start
Synchronization
The main problem with translations is to keep them up to date. It's a bad
solution to feed diffs to each maintainer of the entire translation, i.e.,
if the central maintainer changed a paragraph to clarify a sentence there is
nothing to do for all the translations because they have explained it their
way. So I propose to use a unique skeleton that's a summary of all important
facts. Only changes to this skeleton has to be distributed to the
translators.
The skeleton can be used to discuss the content of new sections or changed
sections to get high quality documents. After we've agreed on a skeleton the
resulting document parts can be written parallel by different authors and in
different languages. It's also possible to automatically check documents how
up to date they are, by building the diffs of the skeletons included in each
document.
Integral part of the skeleton are figures and examples. They are easy
translated and contain the important informations of the section. I think
that our manuals are really good, when the informations can be completely
obtained from the figures and examples.
----------------------------------------------------------------------------
4.1 Skeleton
The skeleton should be an integral part of the document. Therefore it should
be placed somewhere around the sectioning tags. The skeleton area is
introduced with the <skeleton> tag. The whole area is ignored like a comment
by all the target formats. After the <skeleton> tag follows the
corresponding sectioning command. Each aspect is then introduced by
<aspect>. It should contain the central phrase and the corresponding figures
and examples.
<skeleton>
<sect>Skeleton tags
<aspect>start tag
<aspect>aspect tag
<example>dpm0001.expl
<figure>dpm0815.fig
<aspect done>full filled with appropriate content
</skeleton>
The skeleton can contain additional information about the author and/or
maintainer of the skeleton, the date and the version number.
----------------------------------------------------------------------------
4.2 Examples
Most examples will contain some shell commands with the entire results. We
should use a different shell prompt for user commands and superuser
commands. What about
user@debian$
root@debian#
and if the path is important
user@debian[/act/path]$
root@debian[/act/path]#
Lines in examples shouldn't be longer than 75 characters, because it's not
wise to let the formatter restructure the examples.
Where possible examples should be translated. It's therefore important to
use unique strings which can be replaced automatically.
----------------------------------------------------------------------------
4.3 Figures
Figures can be used to visualize most information that's normally described
with text. It's more difficult to put the same information in a picture but
it's worth to take the effort. We are thinking with images and therefor it's
much easier to understand pictures that the written text. Another advantage
is that most images are easy to understand in different languages. There
isn't a speech barrier when exchanging images. That's the reasons why it's
important to have as many figures in our documentation as possible.
Figures can be used for the following items:
* to demonstrate how programs interact
* to show what's a program doing
* to visualize the command line syntax by using small pictographies for
each component
* to show the flow of informations
For our figures we should use a format where the text strings can
automatically be replaced through the language specific ones. Possible
formats include xfig and LaTeX. Both can be converted to a format for the
WWW and printing.
Which format should we use for the WWW? The non-free gif, the free but
sometimes large jpeg or the new not jet known to every web browser png?
<----------- end
Btw, is there a Debian documentation policy!? Should we set one up?
Merry christmas and a happy new year!
Bye
Christian
--
Christian Leutloff, Aachen, Germany
leutloff@sundancer.oche.de http://www.oche.de/~leutloff/
Debian GNU/Linux 1.3.1! Mehr unter http://www.de.debian.org/
Attachment:
pgpNRPwANqkKR.pgp
Description: PGP signature