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 >
