Re: Why does kde-i18n-doc translate outdated documentation?

[Anne-Marie Mahfouf-2]

Hi all,

Cornelius sent a mail recently to the doc mailing list to suggest a meeting. The documentation team is currently very thin but this is an opportunity to revive it.
http://www.nabble.com/KDE-documentation-team-to25838565.html
The situation with userbase should be also clarified. What about users without an internet connection? How do other users find about this doc? This needs to be thought over.
I´ll CC the doc team about this.
What I suggest: it would be nice to have at least 1 active translator at the doc meeting, more if some also want to be a connection between docs and translations. When the meeting details are settled, make sure this list is CCed so you can add your point of view.

Best regards,

Anne-Marie
(currently in Brazil until 2nd November)

----- Mail Original -----
De: "Yuri Chornoivan" <yurchor@...>
À: "KDE i18n-doc" <kde-i18n-doc@...>
Envoyé: Lundi 19 Octobre 2009 14h19:06 (GMT-0300) Auto-Detected
Objet: Re: Why does kde-i18n-doc translate outdated documentation?

Hie

На Mon, 19 Oct 2009 18:56:36 +0300, Burkhard Lück <lueck@...>  
написав:

> Hi translators,
>
> To proof this, the result of a quick and dirty update of the english  
> docbook:
>
> $ svn diff kdepim/doc/ktimetracker/index.docbook |diffstat
>  index.docbook |  231
> ++++++++++------------------------------------------------
>  1 file changed, 41 insertions(+), 190 deletions(-)
>
> No bugreport!
>
> No mail to kde-doc-english!
>
> No mail to this list!
>
> The same happend with several hundred docbooks in the last years.
>
> A really really serious question:
>
> Why does this happen?
> What is going wrong here?
>
> <rant>
> I can not understand that kde-i18n-doc translates silently every nonsens
> documentation, no bugreport, no mail, nothing :-(
> </rant>
>

<ironically>
Yesterday author of this beautiful program told us on IRC that

<quote>
my vision is that I draw ktimetracker's help from userbase.
</quote>

http://userbase.kde.org/Ktimetracker

Now it is a dozen of sentences with 5 screenshots. Author thinks that this  
is enough.
</ironically>

I was also told that userbase team has a vision that docbooks have no  
future and they are ready to replace them by the wiki.

It will be nice to clear up the situation.

Truly speaking, most of the docs are in a similar state. We have to  
correct them all, but have no time: when I join the team there were ~98000  
messages in GUI. Now we have 162000. Shame on me, but sometimes it feels  
like better close my eyes and continue to translate. Sorry.

P.S. What about translation-howto? R.I.P.?
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Albert Astals Cid-2]

A Dilluns, 19 d'octubre de 2009, annemarie.mahfouf@... va escriure:

> Hi all,
>
> Cornelius sent a mail recently to the doc mailing list to suggest a
>  meeting. The documentation team is currently very thin but this is an
>  opportunity to revive it.
>  http://www.nabble.com/KDE-documentation-team-to25838565.html
> The situation with userbase should be also clarified. What about users
>  without an internet connection? How do other users find about this doc?
>  This needs to be thought over. I´ll CC the doc team about this.
> What I suggest: it would be nice to have at least 1 active translator at
>  the doc meeting, more if some also want to be a connection between docs
>  and translations. When the meeting details are settled, make sure this
>  list is CCed so you can add your point of view.

Having a doc that can't be easily translated is like not having a doc. So
translation should not be an afterthough in the doc "solution" but a integral
part of it.

Albert
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Chusslove Illich]

> [: Burkhard Lück :]

> 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.

First 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*.

For 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.")

First 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.

--
Chusslove Illich (Часлав Илић)
Serbian KDE translation team


_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Chusslove Illich]

> [: Albert Astals Cid :]
> Having a doc that can't be easily translated is like not having a doc. So
> translation should not be an afterthough in the doc "solution" but a
> integral part of it.

"Integral" is one way, but I'd prefer "modular" instead :)

I propose that those who intend to do some "new style" documentation
(whatever it may be), do so mostly without considering translation, but
focusing on how to make that documentation useful and maintainable (and
*maintained* :)

As for translations, they should only provide the following:

1. The whole tree of what is to be translated should be made downloadable
_from some location through a file-dedicated protocol, picked from a list of
supported protocols (at least available will be: ftp://, svn://, git://).

2. The whole translated copies of this tree should be uploadable somewhere
as by-language directories, using same or different file-dedicated protocol/
location.

3. Those translated trees should be automatically convertible into form for
end-user consumption.

Important note. These steps *must* be done by the documentation maintainer,
or someone from that same project on maintainer's behalf. They *will not* be
done by anyone from KDE TP. (Of course, as time goes by, canned solutions
may be collected for easy deployment on some typical sources/setups.)

An example. If a piece of documentation is maintained through Mediawiki,
then its maintainer should make articles available through e.g. FTP,
mirroring the wiki tree:

  ftp://somewhere/froobaz/doc/
      About/
          Who_Should_Use_Froobaz.mediawiki
          froobaz_main_window_screenshot.png
          ...
      Tutorials/
          Your_First_Froobazity.mediawiki
          ...
      ...

This tree is of course periodically refreshed, as articles get updated.
Then, there should be a location where translated versions of the tree can
magically appear at, by language:

  ftp://somewhere/froobaz/doc-l10n/
      af/
          About/
              Who_Should_Use_Froobaz.mediawiki
              froobaz_main_window_screenshot.png
              ...
          Tutorials/
              Your_First_Froobazity.mediawiki
              ...
          ...
      ar/
          ...
      as/
          ...
      ...

The documentation maintainer needs only to allow write access by a single
entity (we'll think about authentication) to this location, no other
maintenance needed. Finally, the maintainer needs to establish an automatic
way of putting these translated trees up as wiki pages (they should be
locked for normal editing).

So much about documentation maintainer's side, the other question is who
will make it work behind the scene on translations' side. Since I'm being so
awfully specific, clearly I volunteer to do it. I only don't know when :)
But this is precisely where we can delay and experiment, as having some
*new* untranslated documentation for some months is not the end of the
world.

--
Chusslove Illich (Часлав Илић)
Serbian KDE translation team


_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Chusslove Illich]

> [: Albert Astals Cid :]
> So basically you are proposing a way to do mediawiki -> po and po ->
> mediawiki and po -> docbook/html
>
> What all of us is proposing.

Well, naturally, but I tried to put it in more concrete terms, of who needs
to do what and who needs to maintain what, such that there is least headache
down the road. For example, I specifically do not require of documentation
maintainers to deal with PO files in daily workflow. (Of course, anyone's
welcome to write/find converters for specific formats, that we would use
internally.)

> I disagree however that having new untranslated documentation is
> acceptable.

I think new documentation will take some time to shape up, such that
hopefully there won't be much to translate before support from KDE TP side
is ready (the thingy that will fetch English and put translated documents,
and internal stuff).

--
Chusslove Illich (Часлав Илић)
Serbian KDE translation team


_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Chusslove Illich]

>> [: Chusslove Illich :]
>> I think new documentation will take some time to shape up,
>
> [: Albert Astals Cid :]
> Not really, techbase and userbase already have this problem in this very
> moment.

Indeed I can't argue that's not sufficiently shaped up :)

Well, then someone should start working on wiki->FTP and FTP->wiki parts of
the puzzle for Techbase/Userbase, as in my example a few messages ago. That
someone should know (or get into) wiki technicalities, Techbase/Userbase
setup, and care about having translated documentation, but does not have to
know anything about translation process.

--
Chusslove Illich (Часлав Илић)
Serbian KDE translation team


_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english