[kde-doc-english] Re: Documentation

[Philip Rodrigues]

Hi Jerry,

Sorry I couldn't get back to you earlier - been a little busy with RL.

On Thursday 10 March 2005 03:35, Jerry Diltz wrote:
> It is my desire to work on documenting the GUI useage part of KDE.
>
> I am interested in exploring Linux as a beginner and trying out programs,
> with or without documentation.
>
> Will follow the instructions or hack away a trying to figure out how to use
> something.
>
> It is then that I would like to document my successes.
>
> I wish to start this before I get spoiled using it, learning the acronyms
> and stilll stupid with KDE.

This is certainly an area for which documentation is useful and important, so 
there's plenty to do. I think that this sort of work would fit well in the 
new User Guide. If I didn't link to it in my last message, you can find the 
latest version online at 
http://people.fruitsalad.org/phil/kde/userguide-tng .

There is a difficulty in writing more general documentation because of the 
variety of systems which KDE runs on. For example, tasks such as installation 
of new software vary hugely between one Linux distribution and another, and 
even more when you get to non-Linux UNIX variants (such as FreeBSD, on which 
KDE runs excellently). So it can be hard to make sure that what we write is 
general to KDE and not specific to one distribution.

Now, that's not to say there's nothing we can do - it's a challenge, rather 
than a problem. I'd be interested to hear what others think about our 
approach to such issues, although I'm quite happy with the way we do things 
now (which is to say, we document the default behaviour of KDE, and KDE only, 
and therefore don't mention anything that's distro-specific).

So, after that slightly circuitous argument, something more concrete: I'd 
suggest you keep a copy of the User Guide open while you work/set things up, 
and make a note of things that are good, bad, or missing in the Guide, as 
well as any more general comments - for a particular task, did the User Guide 
have the necessary information? Did it point you to appropriate further help? 
Was it easy to find the right section? etc.

With this information collected, you can send it to the list at regular 
intervals (say, once a week/fortnight), and if you'd like to write about a 
particular topic that you've highlighted, tell us, so we can make sure that 
no one else starts work on it.

That's just a suggestion, so if that way of working wouldn't suit you, get 
back to us, and we'll come up with something else. Either way, I'd suggest 
keeping notes of what you're trying to do, what you found easy/hard and so 
on, to refer to later.

Also, I noticed your comment about the difficulty of getting involved. Could 
you elaborate? We try to make it easy for people to get involved with KDE, 
and documentation in particular, but if we're missing something, we'd like to 
know.

Regards,
Philip

-- 
KDE Documentation Team: http://i18n.kde.org/doc
KDE Documentation Online: http://docs.kde.org