[kde-doc-english] KDE documentation team

[Frank Schoolmeesters]

On Sun, Oct 11, 2009 at 2:06 PM, Anne-Marie Mahfouf
<annemarie.mahfouf at free.fr> wrote:
> 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.
>

Hi,

I do maintain the Krusader documentation for about five years now.
I have asked the Krusader developers to maintain two text files who
allows me to write documentation updates.
Changelog
http://websvn.kde.org/trunk/extragear/utils/krusader/ChangeLog?view=markup
A one line description about what is changed.

SVNNEWS
http://websvn.kde.org/trunk/extragear/utils/krusader/SVNNEWS?view=markup
If a one line description of the Changelog can't explain what the new
feature does exactly, a short description what the new feature does
(e.g.  + hidden keyboard short cuts, mouse actions, ...) .
This allows also that Krusader-SVN users/testers have a explanation of
the new feature when the documentation is not updated yet.

Based on the Changelog and SVNNEWS text files, I update the documentation.
It's an easy solution and developers don't need to be bother with
docbook-xml if they don't want to.

Good software is only good if it's good documented and translated.
Developers should give some minimal information at the documentation editors.
It's a matter of respect for ALL people who are contributing to kde.

Best regards,

Frank Schoolmeesters
http://www.krusader.org


> 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
>>
>
>
> _______________________________________________
> kde-doc-english mailing list
> kde-doc-english at kde.org
> https://mail.kde.org/mailman/listinfo/kde-doc-english
>