From kde-i18n-doc Fri Oct 23 15:55:03 2009 From: Chusslove Illich Date: Fri, 23 Oct 2009 15:55:03 +0000 To: kde-i18n-doc Subject: Re: Why does kde-i18n-doc translate outdated documentation? Message-Id: <200910231755.04267.caslav.ilic () gmx ! net> X-MARC-Message: https://marc.info/?l=kde-i18n-doc&m=125631347617272 MIME-Version: 1 Content-Type: multipart/mixed; boundary="--nextPart314083455.gPUAWky6K6" --nextPart314083455.gPUAWky6K6 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable > [: Burkhard L=C3=BCck :] > 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. =46irst 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*. =46or 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.") =46irst 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. =2D-=20 Chusslove Illich (=D0=A7=D0=B0=D1=81=D0=BB=D0=B0=D0=B2 =D0=98=D0=BB=D0=B8= =D1=9B) Serbian KDE translation team --nextPart314083455.gPUAWky6K6 Content-Type: application/pgp-signature; name=signature.asc Content-Description: This is a digitally signed message part. -----BEGIN PGP SIGNATURE----- Version: GnuPG v1.4.2 (GNU/Linux) iD8DBQBK4dHYMSGXgigGr3ERAsOXAJ9ZZMzf2zJWT9rp5AMabKDvR4rO0ACgqUy6 Yeigjdn5LGFeSN+4xn0WHjs= =84Ew -----END PGP SIGNATURE----- --nextPart314083455.gPUAWky6K6--