Using userbase for manuals

[Yuri Chornoivan]

написане Sun, 01 Jul 2012 10:49:11 +0300, Kevin Ottens <ervin at kde.org>:

> On Sunday 1 July 2012 09:21:08 Albert Astals Cid wrote:
>> El Diumenge, 1 de juliol de 2012, a les 08:02:28, Boudewijn Rempt va
> escriure:
>> > 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
>>
>> I disagree, as a matter of fact, I don't have internet connection in the
>> room in my hostel, so if i had a need to use krita I'd need to read its
>> manual (since my painting/drawing skills are null) and i'd be not happy  
>> to
>> discover I can't read the manual.
>
> It's all very hypothetical isn't it? :-)
>
> More seriously, I think we shouldn't loose perspective here. Yes, you're
> right, it *can* happen, but Boudewijn is also right, it's becoming rare
> situation.
>
> My opinion is that I would love to go for it, and if over time that  
> turns out
> to be a problem, we could ship a dump of the relevant wiki content along  
> the
> application. It'd be used as fallback if the wiki cannot be reached  
> online.
> This way we'd still benefit from the better contribution scalability of
> userbase compared to our current situation. That'd make for a more  
> complex
> solution on the client side though, that's why I wouldn't jump the gun  
> on it
> immediately.
>
> Regards.

Hi,

Just a minor remarks on using UserBase for documentation.

1. It does not matter where you *do not* write your documentation.

New Krita manual was started 5-01-2010 [1]. For now, it is not ready even  
at 1/10 level. The activity is extremely low. The content is badly  
formatted and hardly useful.

The projection can be made (by exploring similar wiki documentation  
projects, like Fedora, openSUSE, Mandriva, and Debian/Ubuntu) that when it  
will be ready it becomes obsolete for the current version.

Example of the manual that once was written and now partially outdated is  
Amarok Manual [2].

2. Simple conversion docbook to wiki does not make manual useful.

Example: Kexi handbook [3] was roughly converted to wiki with broken  
formatting, lost of index, and no substantial changes. Thanks to Burkhard  
it was polished (as a docbook) and converted back thanks to Claus  
Christensen.

3. Manuals can live without wiki conversion.

Examples: Calligra Stage [4] and Calligra Sheets [5] manuals were never  
converted to wiki. For whatever reason, they are now in much more helpful  
state than Words and Krita docs (not saying that they have offline  
versions).

4. Proper formatting allows very easy conversion from wiki XML to docbook.

Once well-formatted, wiki pages can be converted into offline form  
(docbook, PDF, or EPUB) in almost no time[6].

Examples:
Amarok, Kexi, Kdenlive, KrossWordPuzzle, part of KMail offline manuals are  
converted (and slightly fixed) UserBase manuals.

Just for curiosity, you can compare the level of the translation covering  
for these docs in kde-i18n Subversion [7] and on UserBase.

Conclusion

I know that it is hard for developers to keep backward compatibility. But  
please do not cease to maintain DocBook compatibility in KDE 5. If you do,  
you will likely lost most of your docs and most of your documentation  
translators.

I am far from making decision for developers, but it is always good to  
have some plan with real results. Just moving docs in hope that after that  
someone definitely write them is counterproductive.

Just my 2 cents.

Best regards,
Yuri
KDE Ukrainian team coordinator

[1] http://userbase.kde.org/User:Boudewijn/Krita/Manual
[2] http://userbase.kde.org/Amarok/Manual
[3] http://userbase.kde.org/Kexi/Handbook
[4] http://docs.kde.org/development/en/calligra/stage/index.html
[5] http://docs.kde.org/development/en/calligra/sheets/index.html
[6] http://userbase.kde.org/How_To_Convert_a_UserBase_Manual_to_Docbook
[7] http://l10n.kde.org/stats/doc/trunk-kde4/team/