[kde-doc-english] Why does kde-i18n-doc translate outdated documentation?

[Chusslove Illich]

> [: Burkhard Lück :]
> But sadly I had the same experience as with nearly every translation I
> wanted to update or start in the last years:
>
> The documentation is full of wrong and outdated stuff, it is impossible or
> useless to translate it!
> [...]
>
> [But, translators send:]
>
> No bugreport!
>
> No mail to kde-doc-english!
>
> No mail to this list!
>
> A really really serious question:
>
> Why does this happen?
> What is going wrong here?

Apparently, translators enjoy, well, translating. Seeking out and reporting
problems in documentation, especially by running the program, is too much
trouble. I suppose most expect that documentation is reasonably up to date,
or going there, so that it's not a waste of time translating it. The primary
problem, as I see it, is that this expectation turns out to be very much
unfounded. (The problem of sync between translated UI messages and
translated doc is secondary, so I'll skip it for the moment.)

Then, about outdated documentation.

First of all, I consider it shouldn't be translators' duty to force it be
uptodate through salvos of bug reports and other communiques. Documentation
should be uptodate, accurate, purposeful, etc. etc. on its own; only then it
makes sense for a random reader, including a translator, to report an
occasional problem that slipped unnoticed. If a piece of documentation
cannot be maintained in such state, then it simply *should not exist*.

For a piece of software, documentation should be written and maintained by
people who have excellent overall knowledge of it and strong desire to say
something structured about it. This means: core programmers. (Of course,
random people can be shepherded from time to time on point writing tasks.) I
don't buy the "programmers can't write doc" stuff. Programmers aren't
illiterate, are they? Nobody is asking for a Shakespearian play, but hard,
useful, facts. Brag about what the software can do, and how exactly, damn
it.

(I assume it would also be possible for highly involved users, with enduring
interest in the particular piece of software, to the point of following
development channels, to maintain its documentation; I only can't claim I've
positively identified such an example.)

Ok, so it happens that core programmers are very happy chunking out code,
but none would like to write and maintain documentation. No problem -- then
there is no documentation. Maybe no documentation is exactly the right
measure of documentation for target users. However, what I consider zero
sense in that case, is to put out calls to "contribute by writing some
documentation", to "write in any format and someone else will make it format
X", etc. This has no-content-expected and no-maintenance-possible written
all over it.

I propose the following practical steps:

1. "KDE documentation team" immediatelly stops caring about most of the
existing documentation. Instead, they focus on writing and maintaining stuff
that holds for KDE environment in general. Overviews, tutorials, core
components. Examples: description of KDE's file dialog; what are IO slaves
and how they are used; possible workflows with virtual desktops; desktop
visuals; etc. (Each piece should be maintained by someone who thinks it's
the best feature since sliced bread, and who will thus easily notice when
something changes.) This documentation should be well modularized and links
kept stable, such that external documentation can reference it.

2. The requirement that each distinct piece of software in core modules and
extragear has documentation is immediatelly dropped. Lack of documentation
may be taken as a negative point for accepting an application into module/
extragear, but not a decisive one. Especially not if the maintainer
plausibly argues that no standalone documentation is needed or would be of
little use.

3. A way to heuristically determine when a piece of documentation is
outdated is agreed upon. E.g. threshold for number of matching UI messagas
between the doc POTs and UI POTs. Or simply one translator raises flag (on
the i18n ML), and another confirms. POTs corresponding to outdated
documentation (and existing translations) are then moved into
docmessages-unmaintained supermodule. (The way to get it back from there?
Someone sends note "now it's good again.")

First two steps can be carried out by decision, but the last one has some
technical obstacles (beyond determining the method for declaring
outdatedness). I'll say something about that in reply to Albert's message.

-- 
Chusslove Illich (Часлав Илић)
Serbian KDE translation team
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
Url : http://mail.kde.org/pipermail/kde-doc-english/attachments/20091023/56e5b994/attachment.sig