From kde-core-devel Fri Mar 01 12:39:45 2002 From: Lauri Watts Date: Fri, 01 Mar 2002 12:39:45 +0000 To: kde-core-devel Subject: Documentation Disasters X-MARC-Message: https://marc.info/?l=kde-core-devel&m=101498798227370 Important request: Can people who have CVS accounts and plan to=20 write/update/add to documentation please let us know, before you start,=20 and definitely before you commit. In the last week, several thousand (literally!) translations have been=20 lost and this could have probably been avoided. Yes we retrieved them =20 (actually Eric Bischoff, who deserves an enormous amount of thanks for=20 his time), and yes that took many hours that he could have better=20 spent doing new translations, as well as holding up other people and=20 just generally being disheartening. It is *deeply* appreciated if people volunteer to write documentation on=20 their own initiative, but please be aware that committing docs without=20 checking with either me directly or even better kde-doc-english mailing=20 list is causing some real disasters. I'm going to assume it's=20 because you're not aware that these things affect i18n or docs, so I'm=20 going to lay it out for you here. This short rant: If you plan to start writing a document that is currently unmaintained,=20 or you just want to patch one that's already there, please say so on=20 kde-doc-english *BEFORE* you start. =20 If we know you're doing work, we can keep the translation templates in=20 sync. You are more than welcome to do this yourself, please check out=20 all 300 plus Megs of kde-i18n and then ask on the list for instructions=20 on the intricacies of the documentation translation process. You'd=20 rather avoid that? Then work with us, and tell us *BEFORE* you change a=20 document. Don't *EVER* rename a doc file, unless you're going to check out=20 kde-i18n and fix the resulting carnage for every language that has=20 already translated it. You'd rather avoid that? Then if you want=20 document files renamed, ask kde-doc-english or me directly to do it. *ANY* change to translateable strings, including completely removing or=20 adding buttons should get a GUI: tag in their commit. Things with GUI:=20 in their commit logs get forwarded to me separately, and I can forward=20 them on to the documentor concerned, or fix the docs myself, whichever=20 is most efficient.=20 Although you can substantially change an application's behaviour and=20 appearance without affecting translateable strings and breaking the=20 message freeze, do remember that it's still going to make the=20 documentation entirely wrong. Use the GUI: in your commits, or post=20 patches to the docs when you post your patches to the code for review. =20 The long rant for anyone interested is being written as part of the=20 documentation site reorganization. I'll post it in a day or two, along=20 with a specific "Documentation for Developers" Cheat sheet. =20 We deeply appreciate when you write documentation, but it is less=20 appreciated when the result is hundreds of hours work by potentially=20 hundreds of other people is summarily thrown out. Simply keeping us=20 informed would avoid this. Regards, --=20 Lauri Watts KDE Documentation Coordinator