[kde-doc-english] Re: [kde-quality] KDE PIM docs

[Lauri Watts]

On Tuesday 24 February 2004 19.23, Carlos Leonhard Woelz wrote:
> I forgot to add kde-doc-english.

Comments below.  Please note when I am talking about 'stability' I mean, 
stability of interface - whether the application is constantly changing it's 
GUI, which makes documentation much harder work, or if it's fairly 'finished' 
in the GUI.

> Also, the screenshots in almost all modules need update. It seems like a
> very good job for a begginner: fast and gratifying.

Screenshot guidelines are here:
http://i18n.kde.org/doc/screenshots.php

Note, we're a little flexible on the file size, it's not always possible to 
keep them looking nice at that size (clipping window decorations off helps)

> > KMail: relatively well maintained, dnaber is currently updating it.

Daniel has mentioned he's busy and would welcome help.  It's an excellent doc, 

> > KOrganizer: needs work, last update 14 months ago.

This is definitely the one in the worst state.  However, KOrganizer has become 
very stable

> > KAdressbook: updated 5 months ago by tokoe, and got fixes from binner.

Probably worth talking to the developers, how stable the interface is.  It 
hasn't been, historically, and we've had trouble finding a maintainer for it.   
I'm pretty sure tokoe would indeed like someone to take it off his hands (or 
even just update it, if they don't want to be the actual maintainer)

> > Kontact: cshumac added it two months ago, seems reasonably up to date.

It's up to date, and a nice doc, there might be potential to add more 
information to it though, if that interests someone.  

> > KNotes: laurie updated and simplified it 5 months ago. Dunno if it
> > changed much since.

I'm pretty sure it hasn't.  There's more that could be done with it though, 
perhaps a small section detailing how it behaves as a part of kontact, 
cooperation with kpilot and other sync tools.

> > KAlarm: got an update from David Jarvie two months ago.

David keeps this one completely up to date - I'm sure he'd appreciate the 
help, if someone is offering.

> > KNode: last update ages ago

KNode is very stable in interface, there's probably not a whole lot of work to 
be done here.

> > KPilot and Kandy: I don't have the hardware to test this apps, but lets
> > go:

KPilot needs love, indeed, and Kandy, i think we should clarify the status of 
the application - if it is indeed 'permanently on hold' then spending the 
very limited resources available on it, would be a waste.   If that's only a 
temporary status though, now while it's not changing is an excellent time to 
get the doc into shape.

> > KPilot: last update 7 months ago by adridg with the comment "it is still
> > a mess"
> > Kandy: very old docs! I think Kandy holds the record of oldest non-fix
> > commit.

> > KonsoleKalendar: Allan Winter seems to be taking care of it.

This one's always up to date too.  

On documentation quality team jobs generally:
If someone is willing to do a finer grained review, a list of specific issues, 
new items to be added, and things that are no longer accurate, would be a 
huge help for me (and the team), either on a doc-by-doc basis, or for the 
whole module (or indeed, for any document you can find.)  This is a highly 
tedious and time consuming thing to do, and it pretty much eats up the few 
doc resources we have, prior to each release.  

When we have such a list, a competent writer can generally go through and fix 
all the items in a fraction of the time it takes to carefully compare the 
document and the interface and find the changes.   

We often get these filed as bugs (one issue per bug, ideally) by the 
translators, and it's a huge help.  It'd be nice to catch them earlier in the 
process, so the translators don't have to do it (they have limited time too, 
and if they're finding errors, it means the docs are out of date already)    

It's the kind of thing that takes absolutely no experience of any kind, either 
with the app, programming, or writing, and it's a great way to familiarise 
yourself with an application - selling it this way might make this the 
perfect "total beginner but wants to contribute" job.

-- 
Lauri Watts
KDE Documentation: http://i18n.kde.org/doc/
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: signature
Url : http://mail.kde.org/pipermail/kde-quality/attachments/20040225/9e8155bd/attachment.pgp