[kde-doc-english] KDE documentation team

[Anne-Marie Mahfouf]

Hi Cornelius,

I am not sure who is really part of the documentation team at the moment 
(apart from Burkhard who will probably answer your mail as well).

A few ideas and comments that I have, quickly put together

I concentrate mainly on doc for new applications: when a program is in 
kdereview and ready to move in a module, I try to test it and I check the doc. 
If there is none, I write it (thus testing the program even deeper ;). I then 
try to find an English speaker in order to proof it. Andrew Coles does an 
excellent job with that. It is easy to get the developer cooperation as he is 
eager to get his application into KDE main :)

What are the problems with writing docs?
- developers do not bother
- when they bother, the docbook format is too much for them as well as the 
structure of the doc. Some developers though do bother and we help them by 
asking them just a text or any other format that we then put into docbook.
- getting other people to help with doc effort: it's difficult to write docs for 
a program you do not totally know. Also our team is not big enough to help 
newbies.
A meeting would help getting people started.

What for the future?
- use userbase.kde.org for tutorials and keep them up-to-date (although it 
needs internet connection for the users to access them). Example: how to make 
a list of words for Parley? 
How can this work along with a doc?
- make writing docs easier: maybe redo the template. Do we need to explain 
what File-> Quit does in each doc?
- try to make a real doc team
- make patches easy: define a process so any user could write a section of a 
doc and easily submit it.
...
I'd be happy to participate to a meeting if it's possible considering my 
family's duties!

Anne-Marie

On Saturday 10 October 2009 22:26:38 Cornelius Schumacher wrote:
> Hi all,
> 
> (hope this is the right mailing list to discuss KDE documentation in
>  general. If not, please advise where a better place is)
> 
> I was wondering what the state of the KDE documentation team is. Some of
>  the docs are pretty outdated and also our software, prominently
>  KHelpcenter (which ironically apparently still lists me as main developer
>  in the about box) is lacking behind. There wasn't much innovation in KDE
>  documentation land lately. But I think we should change that, and in order
>  to do that we need a strong documentation team. So please understand this
>  as an attempt to help with bulding up new strength for the KDE
>  documentation team.
> 
> There are quite a few things we could do to help with that. One and
>  foremost I think it's a question of coordination. We do have great
>  documentation efforts, the classical documentation, new approaches like
>  Userbase or the knowledge base on opendesktop.org, or also the forums, and
>  of course there is all what's happening for all the distributions which
>  are shipping KDE, and much more.
> 
> So bringing this all together, stimulating some development of new
>  technology, maybe a rethinking of some of the assumptions we do (e.g. is
>  it still essential to be able to print an applications manual), all this
>  could freshen the KDE documentation effort and improve the experience for
>  our users.
> 
> So please let me know, what's the state of the KDE documentation team, what
> ideas do you have how to improve the situation, what can we do?
> 
> One of the obvious ideas would be to get together the people who are
>  working on KDE documentation for a face-to-face meeting. But to be able to
>  organize that we need a better idea of who cares about KDE documentation,
>  and where we are heading.
> 
> All input is welcome.
> 
> Regards,
> Cornelius
>