Using userbase for manuals

[Boudewijn Rempt]

On Sunday 01 July 2012 Jul, Yuri Chornoivan wrote:
> 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.

Yet, it is 100% more than the effort that was expended on the 2.0 docbook manual. The reasons I never got further were:

* no time
* I hate writing wiki markup
* no time

The reason no users took up the effort were:

* I mistakenly tried to keep the manual writing to myself, because I thought I could do the job and create a nice, uniform, consistent manual, just like the Krita 1.6 manual, which people have told me was about the best manual of any KDE app.

That didn't work out. But without the wiki link, the user currently working on the manual would ever have offered his help.

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

That holds for all manuals...

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

That's because those applications didn't change so much; it had nothing to do with the conversion to wiki or not, but more with the applications not changing enough to outdate the manual. Because the 1.x krita manual was so good, it was impossible to update it for 2.0; there was too much that was irrelevant, and it needed to be rewritten completely.

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


-- 
Boudewijn Rempt
http://www.valdyas.org, http://www.krita.org, http://www.boudewijnrempt.nl