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

[Sebastian Kügler]

On Wednesday, August 12, 2015 12:20:29 Luigi Toscano wrote:
> 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).

I know, I reviewed many of them.

> 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).

To be clear, I didn't mean to diminish Burkhard's work, the opposite is true. 
Documentation is important, and people who care about it are doing important 
work. Simple as that. That's why I sat down and wrote the plasma-pa doc, 
instead of lamenting whether it's really needed.

> 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).

Yes and no, but it's offtopic here, so let's not get into this.

> > 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.

Indeed.
-- 
sebas

http://www.kde.org | http://vizZzion.org | GPG Key ID: 9119 0EF9