Documentation (was Re: Plasma Applet for Audio Volume for kdereview)

[Luigi Toscano]

On Wednesday 12 of August 2015 10:05:34 Sebastian Kügler wrote:
> Also, the Evolve survey was pretty clear that we utterly suck in the
> documentation arena. Playing with words doesn't solve that, writing
> documentation and maintaining it does.
> 
> We may change the rules, and that's perhaps what we should do, but that
> doesn't begin with "let's ship a new module without docbook", that should
> begin with a cunning plan to move to online docs, the wiki, etc. and
> integrate that into the help function of applications. Right now the help
> button is a sort-of catch22, docs are usually useless, so I don't see the
> necessity to write them, so they're more useless (or not present).

I've seen many review requests from Burkhard to review tons of documentation. 
He is doing a big work on many modules (few applications receives some hel p 
from the maintainers).
Thanks to maintainers who checked and approved the reviews, but I didn't see 
any request for changing them or updating them before this effort, regardless 
of the format (reading the generated documentation is possible without dealing 
with DocBook).

If you think that the documentation is useless, please report it, just for any 
bug. I don't see why it can't be improved, again regardless of the format. 
Even without thinking about future formats, a simple document in any format 
with the updates is always more than welcome.

About the format, personally speaking, a system which relies only on online 
docs is not going to work, both ways should be possible (offline and online).

> 
> Anyway, discussion in this thread is moot, since I've committed a docbook
> which is hopefully helpful for those who know to find it.
So let's change the thread.

Ciao
-- 
Luigi