Using userbase for manuals

[Dominik Haumann]

Hi,

On Sunday, July 01, 2012 09:21:08 AM Albert Astals Cid wrote:
> El Diumenge, 1 de juliol de 2012, a les 08:02:28, Boudewijn Rempt
> > I'm not concerned that users cannot access the help when they are
> > off-line. That's a vanishingly rare situation these days
> 
> I disagree, as a matter of fact, I don't have internet connection in the
> room in my hostel, so if i had a need to use krita I'd need to read its
> manual (since my painting/drawing skills are null) and i'd be not happy to
> discover I can't read the manual.

Imo, having the docbook is not that bad. We even have tools (like the Kate 
plugin) helping to write it pretty much error-free out of the box.

In Kate, we have some places where we have direct links to the handbook (by 
using anchors in the docbook). As example, look at how editing the modelines 
in the Open/Save dialog works:

  http://wstaw.org/m/2012/07/01/plasma-desktopYD4467.jpg

Here, the help icon appears next to all items, and opens the docbook exactly 
at the correct location. In order to make this work, we need tight control 
over how the linked documentation looks like (the anchors need to be present).

Currently, in Kate we are keeping the docbook pretty much up-to-date as we 
introduce changes to the code. I agree that it's (a lot of) work, but it can 
be done by strictly following this rule.

I'm not convinved at all that a wiki provides us the control over all 
translations to keep the feature mentioned above...

So I'm in favor of docbook, still... What about communication more that the 
documentation is part of the development process and it is a requirement to 
keep it up-to-date?

Dominik