[kde-doc-english] Re: Translating documentation and improving our trads

[Lauri Watts]

On Thursday 12 August 2004 11.31, Kevin Donnelly wrote:
> On Wednesday 11 August 2004 10:06 pm, Gérard Delafond wrote:
> > An idea could be demanding a significant rate of translation in docs to
> > be part of KDE.
>
> This would be bizarre.  As a user, I hardly ever look at the docs, because
> they are of uneven quality (where they exist) and often do not represent
> the latest iteration of the program.  For a translation team, being forced
> to do the docs would be an enormous additional burden, when keeping up with
> the interface is difficult enough - I think many of the translation teams
> for the smaller languages would simply give up.
>
> I also have a fundamental philosophical difficulty with the docs - they
> tell you what a program does, but not necessarily how to use it for a
> particular task.  I tend to think that a collection of tutorials would
> actually be more useful (cf
> http://www.cymrux.org.uk/docs/item.php?lg=en&item_id=20).

Preaching to the choir here.  

"Describe the interface" we consider a bare minimum for docs, and if that's 
all there is, it's a bug.  If we had more than one or two people actively 
involved in writing the things, it's a goal to make all the documentation 
more task oriented.  

We've said this over and over on the docs list, and we're actively rewriting 
the kde user manual to be almost completely task oriented.  We're working on 
ways to automate the 'just describe all the options' part, because it is 
tedious and boring and only a bare minimum that authors (and translators) 
shouldn't have to bother so much with, and this would free up the few 
resources we do have to concentrate on more useful things like task based 
instruction.  The one and only reason the docs are not more task oriented 
than they are, is because nobody is writing.

Why are those tutorials you mention published on some random website that I've 
never seen, and not submitted for inclusion into the KDE docs?  I certainly 
don't have time to google for websites that might contain useful information.

This one, for instance, would make a great "Quick Start" chapter for the 
kdeprinting manual:
http://www.cymrux.org.uk/docs/item.php?lg=en&item_id=31 
and if there was some clear copyright information, I'd reuse it in a 
heartbeat.  However, it's GPL licensed and KDE docs are 
FDL-with-no-invariant-sections licensed, and I don't know who to ask for 
permission to reuse it, since the site doesn't say. 

> Rightly or wrongly, I tend to be in the second group, mainly because I
> think it fits in better with the "release early, release often" philosophy
> of the community development model.  This will probably change as the apps
> mature, but at the minute, with only 40% of KDE translated, typos get fixed
> on an ad hoc basis, and docs are really not on my priority list.

A nice vicious circle this is:  Docs aren't on anyone's priority list, so 
nobody is interested in working to improve them.  Then because they aren't so 
great, and are out of date, people don't consider them a priority. 

Consider this a plea - if you (or anyone out there!) has any (especially 
task-oriented) content, in any format, tell us about it on kde-doc-english.  
Ideally, wth contact information for the copyright holder.  

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/20040812/accef00a/attachment.sig