From kde-core-devel Thu May 31 14:21:07 2001 From: Lauri Watts Date: Thu, 31 May 2001 14:21:07 +0000 To: kde-core-devel Subject: Documentation woes X-MARC-Message: https://marc.info/?l=kde-core-devel&m=99131994628249 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