[kde-doc-english] Documention Updates - Discussion

[Tom Albers]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Hi,

I want to start a discussion about the system of documentation (HEAD/BRANCH) 
of KDE at this moment. The problem I see is as follows:

Current system:
When a new KDE version (like 3.2) is released there will be a document freeze
a couple of months before. From that moment all documentation changes will be 
made to HEAD, so that becomes visible in the next major release (like 3.3). 
So intermediate releases, like 3.2.1 to 3.2.9 will keep the same English 
documentation.

Current translation system:
This depends on the language teams, but the Dutch team tries to update the
translation in the BRANCH during the intermediate releases. These releases
are shipped to the users and it is great to provide them more and more
translations.

Problem #1:
The English documentation is already partly outdated before the version is 
released, because of the freeze a couple of months before the release. The 
updates to correct this are applied in the HEAD, so even in intermediate 
versions the documentation is not updated.
Between the major releases the English documentation becomes very outdated and 
does not follow the GUI anymore, this is frustrating because everyone knows 
there is an updated version available in HEAD. 

Problem #2:
Remember the translation teams that are working in de branch? Because the
English documentation gets outdated, translations are becoming increasingly
difficult. The GUI is changing and the translator is trying to reflect the
current situation... 
A good translator writes some patches for the English documentation, but the 
translator sees that back in the next major release.
When there is a major release, the branch can be copied to HEAD, all the 
patches of scripty will be applied (remember that that is everything in the 
last year or so (from the last major release till now) , so in this release 
there will only be a few correct translation available.

Solution:
We could apply the patches for the English documentation to the BRANCH. The
programs get updated in the BRANCH, so why not do this with the documentation.

This way the gap between gui and docs gets close to one or two minor releases
instead of a major release.

This way the translation teams is also translating a current document. This 
adds to the motivation for the translators. There is nothing so frustrating 
then translating old documents (and knowing HEAD is updated).

I hear you all scream that that would cause the translation teams more work.
This is not necessary true, what we could do is that we stop the automatic
runs of Scripty. You can run make merge or an other tool manually to reflect 
the patches to the current documentation.

The very active translation teams run that every week and remove the
fuzzies every week, so no problem and there is current documentation.

The less active translation teams have the option not to update the 
documentation a while, so a 100% translation can be reached and kept.

The English documenation is up-to-date in the minor releases as well.

I hope this is a constructive mail and I apologize for the size.

Tom Albers
- --
Coördinator Nederlandse KDE Documentatie
Coordinator Dutch KDE Documentation
http://www.kde.nl
-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.2.4 (GNU/Linux)

iD8DBQFAiZercgQkT9GFRQ8RAlprAKDi8Ywx+xshPfHEnyFBp0LGiuZ1aQCfaWAq
WGxv5AAD7CnEGaxTOP2zuE8=
=XvRp
-----END PGP SIGNATURE-----