Using userbase for manuals

[Inge Wallin]

On Sunday, July 01, 2012 07:02:28 Boudewijn Rempt wrote:
> I'm actually not sure kde-core-devel is the right list... But the e.V.
> mailing list certainly isn't, and we don't seem to have any place for
> discussions that affect KDE as a whole.
> 
> In any case, Ingo Malchow said in his blog
> (http://blog.neverendingo.de/?p=125)
> 
> "We have a great userbase.kde.org but developers don’t use it that much,
> nor is there any links from applications towards Userbase."
> 
> Well, actually we have. I replaced the offline help documentation in Krita
> with a link to the manual on userbase. I have done this for two reasons:
> 
> * I couldn't maintain the offline manual anyway after the change to 2.0
> * this way the user gets sent right to the place where they can contribute
> to the manual (and I've got users contributing to it now)
> 
> I'm not concerned that users cannot access the help when they are off-line.
> That's a vanishingly rare situation these days, the big thing is that it
> gets users right where they can fix the manual (Except on windows, where
> the browser invocation seems broken).
> 
> 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...

Instead of writing small snippets here and there in the discussion, I'll 
collect my thoughts in this mail.

I think we are missing something here: I'ts not about the tools.  It's about 
the format.  (and to some extent the placement of the documentation (near the 
code or centrally)).

If we can just agree on a format for our documentation then the question of 
tools is irrelevant. Anybody can use their own tool for editing the content 
and I think we can set up a default tool chain for maintaining it, 
translations and transforming it to something suitable for viewing.

The default used to be and still is docbook, residing in the source tree in 
the source repository.

Advantages:
1. The documentation is close to the source and it's easy to update it even 
during the development phases. True, this didn't happen very often but the 
potential was there.
2. Versioning of the documentation follows the software.
3. Easy to publish at the same time as the software is published.

Disadvantages:
1. Some people (especially some good writers?) are uncomfortable with source 
revision systems, especially git.
2. Some people (especially some good writers?) are uncomfortable with markup 
languages and prefer wysiwyg? I'm not sure but I have the feeling that even if 
we have some awesome doc writers that love docbook I believe that others are 
put off by it.
3. The documentation is somewhat hidden for potential writers due to 1. above.

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.
3. Translations(?) Unfortunately I missed the Akademy presentation on multi-
language wikis but I understand that this is indeed a problem.

I suppose that we could find or create tools to pull the wiki contents and 
create the current binary format for offline viewing. 

What I would like to see is a discussion on what the writers and potential 
writers want to use (tools and formats) and how we as developers can provide 
them with the best toolchain.

And here's a radical suggestion: How about using ODT as the documentation 
format? It is a powerful format, there are some very good tools to edit that 
(one of them just got the Akademy award), there is change tracking features to 
keep track of edits and reviews.  There are also excellent viewers for it.

For translations, there is even an experimental tool for Calligra words that 
sends a selection of text to Google translate and gives you an automatic 
translation back.