Using userbase for manuals

[Eike Hein]

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