[prev in list] [next in list] [prev in thread] [next in thread] 

List:       kde-i18n-doc
Subject:    Re: reusing text blocks and snippets in the documentation +
From:       Chusslove Illich <caslav.ilic () gmx ! net>
Date:       2009-02-14 13:32:18
Message-ID: 200902141432.30224.caslav.ilic () gmx ! net
[Download RAW message or body]


> [: Burkhard Lück :]
> What I have in mind is something like a "folder" solution:
>
> * every docbook text block used more than once should go into a folder in
>   kdelibs, maybe it's a para, a section, a chapter. whats else ...
>
> * this folder is pulled into every kdemodul/doc/common-doc via svn
> externals
>
> * same prodcedure for l10n-kde4/documentation/common-doc
>
> * adapt l10n-kde4/scripts/update_xml

(I'm going to repeat some stuff from IRC, for completeness.)

Firstly, I think the *current* state, with repeating content in different
manuals, is bad not only for the writer and translator (maintenance
difficulty), but also bad for the reader. I'll divide these repetitions into
two categories of bad, from reader's viewpoint:

* Some of the repeated content is rather pointless, especially in this day
  and age: why should a usage manual even contain instructions to build from
  sources? The fact that they are always the same just adds insult to
  injury.

* Why should I go through a certain amount of content, only to realize that
  I've already read it before, in another manual -- or it's a piece of
  common knowledge in KDE environment -- and then search for how much of the
  content I need to skip to continue with the real stuff?

So, while the fix you propose for easying maintenance (for both writers and
translators) I consider technically fine (sans the second point, see below),
I think that the pattern its trying to ease is broken in the first place.

At least with me, there's a psychological effect too. When I find cookie-
cutter sections in the documentation, repetitions of saying nothing above
the apparent only in different terms, it tells me that the documentation was
written because someone said it must be written, rather than because someone
*wanted* to write it, to convey the right stuff to the user. In short, it
reminds me of poor, command-driven documentation of various niche commercial
apps, that I have to deal with on a regular basis.

(By the way, precisely for this reason, I'd drop the requirement to always
have a manual. If the people closely linked with the app -- programmers,
keen users -- have nothing intrinsically to say about how the app is best
used, than noone else should do it just for the sake of requirement.)

Secondly, there is the problem of tightening instead of relaxing
centralization. How are extragear apps, which have no core module associated
to them, supposed to work? What happens (more to the point: who mops up)
when an application is moved from extragear to core module, or vice versa,
or playground, or... To reason about the centralization problems, I do not
think it's even necessary to include possibility of non-single repositories
in the future.

And centralization is not only a technical matter. For example, as you say,
it's currently very hard for a few people to maintain stuff, with duplicated
content everywhere. But, to begin with, I think it's very poor that few
people have to do such stuff in the first place. Ideally, documentation of
a given app should be written and maintained by a persons closely linked to
that app, without necessity to know internals of a central repository.
Whether currently far from this ideal or not, we should not move in the way
which will put extra burden on documentation writers focused on the given
app alone.

My proposition is then the following (same as on IRC): make a set of
documents as part of kdelibs docs, let's call them "KDE Building Blocks",
which are technically just documentation as usual, and going into gritty
details on point topics. They need not be structured as sequential
reading -- though they easily could be -- but such that manual for app X, no
matter where it's developed and who writes, just tells "...follows <link to-
kde-building-blocks>usual KDE4 building procedures</link>...", "...this is
<link to-kde-building-blocks>KDE's standard shortcuts dialog</link>...",
etc.

Starting from current state, that means to simply let outdated cookie-cutter
sections be outdated. As the building blocks piece is ready, go and remove
the outdated section, para, whatever, replace it with a single sentence
pointing where it should (it's quite reasonable to repeat similar pointer
sentences across manuals, as they contain no info on their own and thus
require no maintenance).

As for the static localized documentation in kdelibs (that which is not
translated as usual over PO, which is currently obsolete, etc.), in the end
there should remain pretty much nothing of it. The only exception being the
minimum necessary amount of legalize, that which is due to copyright law
necessary to repeat in each and every piece of documentation.

-- 
Chusslove Illich (Часлав Илић)
Serbian KDE translation team

["signature.asc" (application/pgp-signature)]

[prev in list] [next in list] [prev in thread] [next in thread]