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

List:       kde-core-devel
Subject:    Documentation woes
From:       Lauri Watts <lauri () kde ! org>
Date:       2001-05-31 14:21:07
[Download RAW message or body]

Hi everyone,

There are some issues with documentation that need a little attention, so I'm 
giving everyone a heads-up.

I'd like to make it very clear there is absolutely no objection to having 
developers writing their own documents, or arranging people to write them, 
it's not like you need the documentation team's permission.  

It is *really* important that someone *tells* me about this though, so I can 
make sure it's off the todo list, and the "current status" web page. 
(http://i18n.kde.org/teams/en/current.html in case you didn't know where to 
find it.)

This way I don't go through what happened recently, where a third party 
was working on a document, and we (neither the docs team nor the 
application's maintainer) had no idea, so I had given a volunteer the go 
ahead to take over the manual.  It's not the end of the world, it's not 
really anyone's fault, a compromise has been worked out, and hopefully nobody 
has been working in vain and duplicating effort.  Still, it could have been 
avoided very easily.

There are several applications where developers write their own docs, and so 
long as the docs are valid, that's great, it's one less thing for me to worry 
about.  You'll likely have to put up with someone from the docs team going 
through and doing a little work on the markup, to keep up with the legal 
notices and trademark acknowledgements, but that's about all the interference 
you'll get. 

Note also that writing docs in anything other than English creates some 
speciall difficulties when it comes to translation, so please, write your 
original documentation in English (we have a proofreading team now, who will 
be glad to help.)

So please, as a courtesy, if you intend looking after your own documentation, 
tell us over in doculand!

A second thing, slightly related, is that some developers are struggling 
along with documentation when they really don't want to.  It's very nice if 
you are writing your own documentation, and some of the application 
maintainers are more than happy to (see above.)  If it's a struggle however, 
and is taking up more time than you have, again... tell me.  I'm not psychic, 
and if I see that there is current and regularly updated documentation for an 
application, it'll not get onto the todo list in the first place, and it'll 
be marked as up to date on the current status page.  End result: nobody will 
volunteer to help you.  

So kind of the opposite of the last request, if you have an app in KDE CVS 
are looking after your own documentation, and don't really want to be, then 
please tell me, so I can start looking for help.  I can't promise it'll be 
instant, or even soon, but there won't be any help at all if I don't know 
it's needed.  I might even come up with the odd volunteer for kdenonbeta 
apps, if they're new/maintained ones.

Finally: can we please *not* upload the entire documentation template to CVS 
if you haven't written any docs, but want a document in place.  A simple "The 
docs were incomplete when you installed this application, please ask any 
questions on the appropriate KDE mailing lists" is much friendlier to the 
users, and will definitely make the translators happy, than a dummy document 
with fake contents. 

That's all folks, back to your regularly scheduled coding,

Regards,

-- 
Lauri Watts
KDE Documentation coordinator

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