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

List:       kde-core-devel
Subject:    Documentation Disasters
From:       Lauri Watts <lauri () kde ! org>
Date:       2002-03-01 12:39:45
[Download RAW message or body]

Important request: Can people who have CVS accounts and plan to 
write/update/add to documentation please let us know, before you start, 
and definitely before you commit.

In the last week, several thousand (literally!) translations have been 
lost and this could have probably been avoided.  Yes we retrieved them  
(actually Eric Bischoff, who deserves an enormous amount of thanks for 
his time),  and yes that took many hours that he could have better 
spent doing new translations, as well as holding up other people and 
just generally being disheartening.

It is *deeply* appreciated if people volunteer to write documentation on 
their own initiative, but please be aware that committing docs without 
checking with either me directly or even better kde-doc-english mailing 
list is causing some real disasters.    I'm going to assume it's 
because you're not aware that these things affect i18n or docs, so I'm 
going to lay it out for you here.

This short rant:

If you plan to start writing a document that is currently unmaintained, 
or you just want to patch one that's already there, please say so on 
kde-doc-english *BEFORE* you start.    

If we know you're doing work, we can keep the translation templates in 
sync.  You are more than welcome to do this yourself, please check out 
all 300 plus Megs of kde-i18n and then ask on the list for instructions 
on the intricacies of the documentation translation process.  You'd 
rather avoid that? Then work with us, and tell us *BEFORE* you change a 
document.

Don't *EVER* rename a doc file, unless you're going to check out 
kde-i18n and fix the resulting carnage for every language that has 
already translated it.  You'd rather avoid that?  Then if you want 
document files renamed, ask kde-doc-english or me directly to do it.

*ANY* change to translateable strings, including completely removing or 
adding buttons should get a GUI: tag in their commit.  Things with GUI: 
in their commit logs get forwarded to me separately, and I can forward 
them on to the documentor concerned, or fix the docs myself, whichever 
is most efficient. 

Although you can substantially change an application's behaviour and 
appearance without affecting translateable strings and breaking the 
message freeze, do remember that it's still going to make the 
documentation entirely wrong.  Use the GUI: in your commits, or post 
patches to the docs when you post your patches to the code for review.  

The long rant for anyone interested is being written as part of the 
documentation site reorganization.  I'll post it in a day or two, along 
with a specific "Documentation for Developers" Cheat sheet.  

We deeply appreciate when you write documentation, but it is less 
appreciated when the result is hundreds of hours work by potentially 
hundreds of other people is summarily thrown out.  Simply keeping us 
informed would avoid this.

Regards,
-- 
Lauri Watts
KDE Documentation Coordinator
[prev in list] [next in list] [prev in thread] [next in thread]