Re: internationalisation/skeleton was Re: another user manual chapter
(due to sad family circumstances it took somewhat longer to reply)
Hi,
Christian Leutloff <leutloff@sundancer.oche.de> writes:
[snip]
> 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.
Excellent ideas!
> <------------------ 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.
The only possible problem in using language specific terms in figures
might be the different space needed, but let's see how it works out.
> 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
Christian, excellent proposal. I'm absolutely in favour of using it.
Why don't we make this a goal/policy for Debian 2.1?
Concerning the graphic format, I propose to use gif or jpeg (maybe
depending on the resulting size, maybe) for now until png is viewable
by the majority of browsers.
Thanks,
Ardo
--
Ardo van Rangelrooij
home email: ardo.van.rangelrooij@tip.nl, ardo@debian.org
home page: http://www.tip.nl/users/ardo.van.rangelrooij
PGP fp: 3B 1F 21 72 00 5C 3A 73 7F 72 DF D9 90 78 47 F9
--
TO UNSUBSCRIBE FROM THIS MAILING LIST: e-mail the word "unsubscribe" to
debian-doc-request@lists.debian.org .
Trouble? e-mail to templin@bucknell.edu .
Reply to: