On 07/01/2012 07:02 AM, Boudewijn Rempt wrote:
After yesterday's discussion where David said that for frameworks/qt5 the help center invocation is actually one of the trickier things, I'm giving this out for consideration for other app developers...
Over at Konversation we've likewise struggled to keep our Docbook manual going: It's still among the better ones around, but we've been terribly lazy and let it rot, and if it hadn't been for Burkhard Lück showing it some love last year, it'd would probably be too outdated to use by now. At the same time we're doing reasonably well at maintaining our Userbase presence. We used to have our own MediaWiki installation but migrated everything to Userbase last year, and I wrote some software that sends report mails to our development mailing list highlighting changes and new pages so we can review them and make sure the quality stays high. Newly written documentation is now usually added to the wiki, not the manual, e.g. I wrote this this month: http://userbase.kde.org/Konversation/Configuring_SASL_authentication I can't really put my finger on it, but somehow it's just more convenient and enoyable to do it in the wiki. It gets you easy preview, makes collaboration easier, and somehow it feels like a more appropriate place for topic-focused guides than the book- structured Docbook manual. At the same time topic-focussed guides seem to be the best fit for us, because being an IRC client our helpdesk naturally is the IRC channel and handing out links that answer a particular question comprehensively works very well there. Ultimately Albert isn't wrong with his concern, but the reality seems to be that we just can't get our act together on the offline documentation while maintaining the wiki comes a lot easier to us. And it's better to have wiki documentation than no good documentation, IMHO. -- Best regards, Eike Hein