Documentation (was Re: Plasma Applet for Audio Volume for kdereview)
luigi.toscano at tiscali.it
Wed Aug 12 11:20:29 BST 2015
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
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.
More information about the kde-core-devel