[kde-doc-english] Documentation and i18n

[Lauri Watts]

Hi all,

I would like to address some issues that have recently arisen regarding 
translation and documentation for extra-gear releases.  

This mail is very long, and detailed.  I'll be taking a test and giving a 
grade at the end (ok, just kidding about the test, but *PLEASE* read it.  
These same issues keep coming up over and over, and they can all be quite 
easily avoided.)

1: It is *very* important to put any translators you have to the KDE 
coordinator for that language. You can always find the appropriate name here:
http://i18n.kde.org/teams/  
If you can't get a response, you can write to kde-i18n-doc at kde.org

If you want consistent translation and terminology with the rest of KDE's 
applications (and why wouldn't you?) this matters.  Worse, you don't want to 
risk losing your enthusiastic new contributor of translations because their 
work was never used, since the i18n coordinator had no idea they existed.  No 
that is not a hypothetical case, it's happened, more than once.

2: It is very useful to put documentation writers in touch with the 
documentation team early on in the process too.  If you get documentation 
sent to you and don't want to deal with it, please send it on to us 
(kde-doc-english at kde.org) or commit it to trunk and tell us about it.  Twice 
in recent weeks I have had a contributor hunt me down, with very hurt 
feelings, to ask why their documentation has not been used.  It's not very 
satisfying to give them an answer of "what doc?"  Worse when one of the 
people blown off by not having their doc committed (and me not knowing about 
it) was also the contributor of one of the translations that got dumped in 
point 1.  You can imagine, he's really thrilled with the whole open source 
development process just now, and I can't say I blame him.

3: Apparently many -extragear apps support much older than the current stable 
kdelibs release.  It would be hugely useful if we *knew* that.   Can you 
communicate it to i18n/docs when you announce a freeze?  Can you put this 
information in yourapp/README?  Both?  Please?  
It's hardly fair to complain to an i18n team for using their normal workflow, 
when they had no idea they were supposed to treat your 
application/documentation quite differently.

4: this has been explained before, but needs to be gone over again.  If you 
want proper translations and proofreading, we need *at least* a 2 week lead 
time before tarballs are made.  Why?

4a: A week or so proofreading time - announce that you're going to have a 
freeze in a weeks time.  There's no use proofreading an app that now has 
frozen strings, because they cannot be *fixed*.

4b: Freeze the strings *entirely* for at least a week.    That means, stop 
changing things.  At all.  No matter what they are.  The translators can not 
keep up with a moving target even normally, and a week is a very short 
turnaround time for them, as much as it may seem an eternity to you.  

4c: Stable branches are nice for i18n.  And bugfixes.  Even if you think it's 
dead, do consider keeping a stable branch open (but string frozen) so more 
i18n teams can get caught up (did I mention how short a week's turnaround is, 
most of the i18n teams are very shorthanded.) Also I could fix almost all the 
issues caused by at least 2 and 3, in minutes, but that's no use to users if 
they have to wait a year for the next trunk release.

5: Please check your tarballs install documentation and translations in the 
right place.  Specifically:
for a doc/Makefile.am that contains KDE_DOCS=AUTO you *MUST* have a 
doc/appname directory.  At least one of the release scripts is screwing this 
up.  

Executive summary:
1: If someone offers you a translation, whether they haven't started or it's 
complete, if it's in SVN or not, please notify the i18n coordinator for the 
language.
2: If someone offers you documentation, in any shape or form or level of 
completion, please contact kde-doc-english at kde.org and say so.
3: Please make it very clear when announcing freezes what kdelibs you're 
depending on.   If y'all can come up with a consistent place to store this 
information so we can look it up ourselves, that's fine too.
4: Please announce you're going to have a freeze, before having it.  And then 
when you do have it, please stick to it. Please consider keeping stable 
branches open.  You'll get more translations that way.    Do consider a .1 
bugfix/i18n release a month or so later, the way KDE does.
5: Please do some basic installation testing of your application's auxiliary 
files.  Does the Help button work? Does pressing F1 work? If you have any 
existing translations, if your app is run with KDE_LANG=something-else does 
the interface in fact change language? do the Help and F1 buttons still work? 
(You don't need to speak a language to check that.)  If no to any of the 
above, please fix your svn to release extraction script, it's broken.

Regards,
-- 
Lauri Watts
KDE Documentation: http://docs.kde.org
KDE on FreeBSD: http://freebsd.kde.org
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 187 bytes
Desc: not available
Url : http://mail.kde.org/pipermail/kde-doc-english/attachments/20050620/9460abae/attachment.sig