KDE documentation team

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

--
Cornelius Schumacher <schumacher@...>
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Anne Wilson-5]

On Saturday 10 October 2009 21:26:38 Cornelius Schumacher wrote:
> 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.
>
You will have seen my efforts via blogs to get more people involved in
userbase.  I confirm that I would like to be part of any effort to improve KDE
documentation, including a face-to-face meeting.

Anne
--
New to KDE4? - get help from http://userbase.kde.org
Just found a cool new feature?  Add it to UserBase


_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Anne-Marie Mahfouf-2]

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
>

_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Burkhard Lück]

Hallo Cornelius,

your mail is very appreciated here.

It's a chance to get some people interested in the KDE Documentation together
and revive the documentation team.

Unfortunately I have to leave soon for a conference and will be offline till
next weekend.

As a start I'll try to summarize the current state of the documention
/translation in svn and my thoughts how to improve that in cooporation with
userbase and forum.

It also would be helpfull to get some input from Phil, the only member of the
former doc team known to me.

Phil?

--
Burkhard Lück
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Burkhard Lück]

1) Status of documentation in kde svn
  branch 330 docs, ~ 100 updated in 2008/9 = KDE 4.x
  kdeadmin (kpackage, ksystemlog)
  kdebase (dolphin, kdepasswd, konsole, kwrite, ~20 kcms, plasma,
  systemsettings)
  kdeedu (blinken, kalgebra, kalzium, kanagram, kbruch, kgeography, klettres,
  kmplot, ktouch, kturtle, kwordquiz, marble)
  kdegames all docs
  kdegraphics (kruler, okular)
  kdepim  6 docs
  kdesdk  6 docs
  kdeutils 7 docs
  lot of technical docs (manpages, ioslave info etc)
 
  Outdated:
  kdeaccesibilitiy, kdebase (userguide etc), kdegraphics, kdemultimedia,
  kdenetwork, kdepim, kdewebdev
  plasma has only a handbook from 2008, no docs for kdeplasma-addons and
  no way to access the khc docs
 
  trunk has around 442 docs, ~ 150 updated in 2008/9

  Until kde 3.4 the documentation was always slightly outdated (e.g. kde 3.4
  with docs 3.3) due to the release schedule (string freeze policy)
  Formally this freeze rules are still valid, but since 3.5.? in practice we
  backport every 4 weeks

  exclude outdated language docbooks from a release (older than x.y version
  then the current code)? An essentials limit similar to
  http://l10n.kde.org/stats/gui/trunk-   kde4/essential/ for gui

2) Changes to the documentation

- target of docs: user with distro packages, not users building from source
  -> remove install.intro.documentation + install.compile.documentation
  and the like
  users building from source get their information via techbase

- current doc system: pull centralisized infos via entities into all docbooks
  every docbook has a settings + help menu, that is boring

- lot of duplicated infos (e.g. about common tasks like file open dialog,
  shortcut + toolbar settings etc)

- This is the start of a discussion about reusing text blocks and snippets
  in the documentation + translation
  http://lists.kde.org/?l=kde-doc-english&m=123456838425128&w=2
  and it ended in this mail by Chusslove Illic
  http://lists.kde.org/?l=kde-i18n-doc&m=123461844907311&w=2
  Maybe a way to go?
 
3) Khelpcenter

* in case there is no documentation khc currently shows an error messages
  "There is no documentation available for foo/index.html" + an additional
  dialog you have to close.
  Replace this with a html page containing:
  - a link to docs.kde.org
  - a link to userbase.kde.org
  - a link to forum.kde.org
  - a link to user mailing lists
  - load missing documentation? (http://apachelog.blogspot.com/2009/10/kde-
distro-package-splitting-100-fail.html)

* cleanup the navigation tree
- rm "Control Center Modules" see now outdated mail
http://lists.kde.org/?l=kde-doc-english&m=122303347319776&w=2
- better names of top items?
- do we really need all these top level entries like "KInfoCenter Modules" /
"KIOSlaves" / "The KDE FAQ" / "Contact Information" etc
- a mix of single docbooks and top level items, unsorted
- separate kde information + docs from scrollceeper/Unix man pages/Browse Info
pages

* no activ assignee for khc bugs

* search htdig -> desktop search

* make it possible to switch from language to english documentation, if that
is more up to date

* toolbar with actions for docs.kde.org, userbase.kde.org, forum.kde.org, user
mailing lists,
  switch to local installed english docs (if more up to date) ?

* keywords in docbooks -> unused

4) docbook - userbase - forum

- different workflows and capabilities (easy to contribute, power of scripting
via pology and other scripts...)

- we need a bridge between userbase and docbook in svn
  e.g. export english text from wiki to docbook -> translation + generation
  of language docbooks -> import them to wiki

We really should have a meeting to learn more about the different workflows,
needs, possibility of cooperation and...

Attendees:
Anne, Anne-Marie, Cornelius?, me, Coles?, Yuri?, a translator from a small
translation team, and everybody else interested in documentation

Where and when?

--
Burkhard Lück
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Anne Wilson-5]

On Thursday 22 October 2009 21:22:28 Burkhard Lück wrote:

> 1) Status of documentation in kde svn
>   branch 330 docs, ~ 100 updated in 2008/9 = KDE 4.x
>   kdeadmin (kpackage, ksystemlog)
>   kdebase (dolphin, kdepasswd, konsole, kwrite, ~20 kcms, plasma,
>   systemsettings)
>   kdeedu (blinken, kalgebra, kalzium, kanagram, kbruch, kgeography,
>  klettres, kmplot, ktouch, kturtle, kwordquiz, marble)
>   kdegames all docs
>   kdegraphics (kruler, okular)
>   kdepim  6 docs
>   kdesdk  6 docs
>   kdeutils 7 docs
>   lot of technical docs (manpages, ioslave info etc)
>
>   Outdated:
>   kdeaccesibilitiy, kdebase (userguide etc), kdegraphics, kdemultimedia,
>   kdenetwork, kdepim, kdewebdev
>   plasma has only a handbook from 2008, no docs for kdeplasma-addons and
>   no way to access the khc docs
>
>   trunk has around 442 docs, ~ 150 updated in 2008/9
>
>   Until kde 3.4 the documentation was always slightly outdated (e.g. kde
>  3.4 with docs 3.3) due to the release schedule (string freeze policy)
>  Formally this freeze rules are still valid, but since 3.5.? in practice we
>  backport every 4 weeks
>
>   exclude outdated language docbooks from a release (older than x.y version
>   then the current code)? An essentials limit similar to
>   http://l10n.kde.org/stats/gui/trunk-   kde4/essential/ for gui
>
> 2) Changes to the documentation
>
> - target of docs: user with distro packages, not users building from source
>   -> remove install.intro.documentation + install.compile.documentation
>   and the like
>   users building from source get their information via techbase
>
> - current doc system: pull centralisized infos via entities into all
>  docbooks every docbook has a settings + help menu, that is boring
>
> - lot of duplicated infos (e.g. about common tasks like file open dialog,
>   shortcut + toolbar settings etc)
>
> - This is the start of a discussion about reusing text blocks and snippets
>   in the documentation + translation
>   http://lists.kde.org/?l=kde-doc-english&m=123456838425128&w=2
>   and it ended in this mail by Chusslove Illic
>   http://lists.kde.org/?l=kde-i18n-doc&m=123461844907311&w=2
>   Maybe a way to go?
>
> 3) Khelpcenter
>
> * in case there is no documentation khc currently shows an error messages
>   "There is no documentation available for foo/index.html" + an additional
>   dialog you have to close.
>   Replace this with a html page containing:
>   - a link to docs.kde.org
>   - a link to userbase.kde.org
>   - a link to forum.kde.org
>   - a link to user mailing lists
>   - load missing documentation? (http://apachelog.blogspot.com/2009/10/kde-
> distro-package-splitting-100-fail.html)
>
> * cleanup the navigation tree
> - rm "Control Center Modules" see now outdated mail
> http://lists.kde.org/?l=kde-doc-english&m=122303347319776&w=2
> - better names of top items?
> - do we really need all these top level entries like "KInfoCenter Modules"
>  / "KIOSlaves" / "The KDE FAQ" / "Contact Information" etc
> - a mix of single docbooks and top level items, unsorted
> - separate kde information + docs from scrollceeper/Unix man pages/Browse
>  Info pages
>
> * no activ assignee for khc bugs
>
> * search htdig -> desktop search
>
> * make it possible to switch from language to english documentation, if
>  that is more up to date
>
> * toolbar with actions for docs.kde.org, userbase.kde.org, forum.kde.org,
>  user mailing lists,
>   switch to local installed english docs (if more up to date) ?
>
> * keywords in docbooks -> unused
>
> 4) docbook - userbase - forum
>
> - different workflows and capabilities (easy to contribute, power of
>  scripting via pology and other scripts...)
>
> - we need a bridge between userbase and docbook in svn
>   e.g. export english text from wiki to docbook -> translation + generation
>   of language docbooks -> import them to wiki
>
> We really should have a meeting to learn more about the different
>  workflows, needs, possibility of cooperation and...
>
> Attendees:
> Anne, Anne-Marie, Cornelius?, me, Coles?, Yuri?, a translator from a small
> translation team, and everybody else interested in documentation
>
> Where and when?
>

My blog of yesterday, http://lydgate.org/blogs/?p=66, is setting out my

thoughts on these subjects, as I have spoken to both Burkhard and Albert
Astals Cid regarding them.  The forum team are allowing me to have access to a
sandbox on their server - it is being set up this morning - so that we can
test out the extensions suggested.  I hope this helps.

Anne
--
New to KDE4? - get help from http://userbase.kde.org
Just found a cool new feature?  Add it to UserBase


_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

[Frank Schoolmeesters]

On Sun, Oct 11, 2009 at 2:06 PM, Anne-Marie Mahfouf
<annemarie.mahfouf@...> 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@...
> https://mail.kde.org/mailman/listinfo/kde-doc-english
>

_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english

On Thursday 22 October 2009 22:22:28 Burkhard Lück wrote:
> 1) Status of documentation in kde svn
(...)

This is very interesting information. Sounds like we have some room for
improvement ;-)

> 2) Changes to the documentation
(...)

> - This is the start of a discussion about reusing text blocks and snippets
>   in the documentation + translation
>   http://lists.kde.org/?l=kde-doc-english&m=123456838425128&w=2
>   and it ended in this mail by Chusslove Illic
>   http://lists.kde.org/?l=kde-i18n-doc&m=123461844907311&w=2
>   Maybe a way to go?

Sounds like a good idea. My personal impression is that our documentation
lacks a bit of a user focus. It's dominated by too many technical and
implementation details. I think we can improve that, and the suggestions are
a good first step.

> 3) Khelpcenter

> * no activ assignee for khc bugs

The main problem of KHelpcenter is that nobody is working on it. It's probably
not perceived as a rewarding task by developers, as it's not very clear how
and if it's used by users, and the details of handling docbook display and
all the rest KHelpcenter deals with can be pretty tedious.

> We really should have a meeting to learn more about the different
> workflows, needs, possibility of cooperation and...
>
> Attendees:
> Anne, Anne-Marie, Cornelius?, me, Coles?, Yuri?, a translator from a small
> translation team, and everybody else interested in documentation

Who could represent translators? Do you have a concrete idea?

I would like to use the meeting to bring together people of all the different
documentation efforts in KDE, traditional documentation, Wikis, forum,
knowledge base, translators. Did I miss any area?

> Where and when?

I'll compile a list of potential participants and come up with a proposal for
a date and place.

--
Cornelius Schumacher <schumacher@...>
_______________________________________________
kde-doc-english mailing list
kde-doc-english@...
https://mail.kde.org/mailman/listinfo/kde-doc-english