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
