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

List:       kde-i18n-doc
Subject:    Re: Translating documentation and improving our trads
From:       Kevin Donnelly <kevin () dotmon ! com>
Date:       2004-08-12 14:27:55
Message-ID: 200408121527.55772.kevin () dotmon ! com
[Download RAW message or body]

Hi Lauri 

On Thursday 12 August 2004 11:20 am, Lauri Watts wrote:
> "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.

I'm glad to hear that.  I make some suggestions below.

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

??? It's not random to me or the people it was written for (users of a liveCD 
to publicise KDE in Welsh) - in fact I've mentioned it a couple of times on 
the list. :-)

Things aren't quite as simple as this, anyway.  
(1) Our sites have various webapps on them, and they can't just be transferred 
to KDE servers - the admins might justifiably have security concerns.  
(2) The tutorial is using the Welsh screenshots - new shots (in English) might 
have to be taken for inclusion in KDE docs.
(3) This particular app (Psi) isn't part of KDE.
(4) The tutorial will probably be out of date in a couple of months, as the 
developers add new bits to the interface, and then it needs to be done again 
- I've done tutorials for SUSE and Scribus which were out-of-date within 5 
months.

So to me it makes sense to have a tightly-focussed site which gives the basics 
on those apps which are translated to date, without having to get involved 
with wider KDE style-rules.

Having said this, if there is a genuine desire to tackle docs in a 
task-oriented way, then I would be very happy to help.  If I were doing this 
from scratch, I would do it as follows:
(1) Select a number of "key" apps, and make a list of things that users might 
need to do to get going (eg on KMail, setting up an email account; on the 
desktop, changing icons, fonts, and labelling) - some of these might already 
be covered in the existing docs, and in that case all that would be required 
is to extract them (although more walkthrough screenshots might be needed).
(2) Put the list up somewhere, and ask each translation team to claim a few 
(but see also below).
(3) The walkthroughs could be submitted in any of the main European languages 
(this may be important for some, who may not feel able to labour their way 
through doing tutorials in English, but could do one relatively quickly in 
their own language).
(4) Post the submitted walkthroughs, and allow each translation team to 
translate the ones they think relevant.

Provided the tutorials were kept very focussed, you could end up with quite a 
range of short pieces, which could then be bundled as an appendix to the 
formal docs.  The most time-consuming thing at (4) would be redoing the 
screenshots.  It might also be easier to keep a number of shorter pieces 
up-to-date with the interface changes.

I wonder, in fact, whether it might not be reasonable to take a "KDE-Look" 
approach, rather than an i18n one.  That is, set up a site which people can 
submit their own tutorials to, and let things go from there.  There could be 
a dummy structure file, and a list of desired walkthroughs, but basically 
people could submit whatever they like, in whatever format they like, with 
others doing translations into their own languages as they see fit.  Just a 
thought.  (The only problem with this is that I read on the KDE site 
somewhere that screenshots have to be taken with specific themes and colours, 
to make KDE look more "professional", and certainly in the first iteration of 
such user-contributed tutorials it is unlikely that this would happen!)

> 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

Glad you like it.  I think Michel Goffioul and colleagues made the most 
important single contribution to making Linux a viable desktop system when 
they wrote KPrint.

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

Er, info@thinkopen.co.uk on the front page?  I give you (or anyone else) 
permission to (re)use/amend anything on the site under any free license 
whatever.

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

Yes, this is a valid point, unfortunately :-(  Doing short docs focussed on 
tasks, though, might make it easier to keep them up to date.

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

I'm happy to pass on anything I do in the future, and if others think a 
"tutorial hub" would be a good idea, I would certainly like to help with it.

-- 

Pob hwyl (Best wishes)

Kevin Donnelly

www.kyfieithu.co.uk - Meddalwedd Rhydd yn Gymraeg
www.cymrux.org.uk - Linux Cymraeg ar un CD!
[prev in list] [next in list] [prev in thread] [next in thread]