Using userbase for manuals

[Ingo Malchow]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Am 03.07.2012 18:07, schrieb 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...

Indeed, and probably one of the times where diversity is not
necessarily improving the situation. It might only lead to just
another tool, which is a) not used or b) used and reduces quality of
existing other wikis due to missing motivation, which are - if i
understood correctly - not supposed to be closed.

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

In an ideal world we could really work around such issues with some
semi-automated ways.
Just an idea:
Those who do like the idea of doing a manual in a online wiki could
just teach their respective users how to properly format their manual.
This reduces the overhead on developers, but also improves the
integration of user contribution.
Once a release is about to happen the page can be closed (protected
from further editing) and exported to docbook and put into some
git/svn repo. This needs some adjustments on the docbook export, but
those are technical details, so i skip that here.
At the same time our group leaders for languages can be poked to
review their translations on the current state of it. Which is AFAIR
the workflow on the offline translations as well.
Now you can easily translate on- or offline in the usual way and it
can finally be merged in the final manual release.

As sidenote for those without internet, we can also produce a pdf at
release dates, not sure everybody is aware of that.

Much of it needs some admin being around, but that is not a problem
anymore these days, response time is usually less than a day.

This is just an idea which could improve the combination of both
workflows, as i see benefits in both of them (vcs "vs." web)

Cheerio,

- -- 
Ingo Malchow
(neverendingo)

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v2.0.18 (GNU/Linux)
Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/

iEYEARECAAYFAk/zHMkACgkQgFDgF4YW7se18ACfT6U91LaFVRwXk7R+5mgxEYTS
0XIAoKsBKJVMKhLi3XJB7Ijs3kM0EZkk
=UNU0
-----END PGP SIGNATURE-----