Using userbase for manuals

[Aurélien Gâteau]

Le mardi 3 juillet 2012 15:18:37 Ingo Malchow a écrit :
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> Am 03.07.2012 14:00, schrieb Aurélien Gâteau:
> > Le lundi 2 juillet 2012 07:01:06 Inge Wallin a écrit :
> >> Now, the suggestion was to move to a wiki instead
> >> 
> >> Advantages: 1. Easier to find the documentation for potential
> >> writers. 2. (Supposedly) easier to edit [Personally I'm not sure
> >> that editing advanced wiki markup is easier than docbook]
> >> 
> >> Disadvantages: 1. Difficult to maintain different versions of the
> >> documentation for different versions of the software. 2. Users
> >> need to be online to view the documentation. I think that
> >> calling this problem "vanishingly rare" is a very northern Europe
> >> centric view. And even I who have excellent broadband often still
> >> do work offline sometimes.
> > 
> > Have it been considered to use a git-based wiki? Such a solution
> > could make it possible to: - keep documentation within the code (or
> > close enough) - web editing for people who are not familiar with
> > git, offline editing for advanced users (or for when you want to
> > write documentation offline) - branching the documentation to
> > follow versions
> > 
> > One could probably produce offline KHelpCenter-compatible
> > documentation from it.
> > 
> > I know at least one wiki which is git-based: Ikiwiki [1][2]. I have
> > no idea if it can be adapted to our needs, but I think it is an
> > approach worth looking at.
> > 
> > [1]: http://ikiwiki.info/ [2]:
> > https://en.wikipedia.org/wiki/Ikiwiki
> 
> There is also gitit. But from what i can tell, they don't provide a
> way to import content from mediawiki. And looking at the number of
> pages our wikis have at this stage, this is a major drawback.
> Additionally we will loose support for quite some plugins, most
> notably the translate extension, which is integral part of this entire
> discussion. So we would be back at manually copying the english
> original and translating an entire page without being notified of
> further changes to the original.

I don't think one need to have all wiki content transfered to a git-based 
wiki. I see this as a new tool to collaboratively write documentation which 
happens to be a wiki, but not necessarily as a replacement for our existing 
wikis. But then, having different wikis can (will) lead to problems...

> All that for the sake of using a commandline tool instead of a browser?

Being able to use a commandline tool is just a (nice) side-effect. The main 
advantage of a git-based wiki is being able to branch the wiki for releases.

Aurélien