[kde-doc-english] Proposal to use (docbook)wiki for docs

[Richard A. Johnson]

I have no problem with documentation on the wiki, however making it "official" 
documentation is not a good idea. What we should look at doing in the future is 
something GNOME has created a project for (Project Mallard: 
http://live.gnome.org/ProjectMallard). We could even work with GNOME and look at 
creating a desktop independent help system that would eliminate having to 
install Yelp or KHelpCenter on each others environment when we choose to use a 
product from the other team.

Personally, I feel that using a wiki for documentation to be used for the main 
help within a system is somewhat of a cheap hack. KHelpCenter needs help, we 
know that, documentation needs help and we know that too.

I will not accept that using a wiki will make it easier for people to contribute 
to documenting KDE. A few months back, both Bernard and Jonathan can attest, I 
posted a blog post that said we needed help with docs, and guess what? We got 
flooded with help requests and even got 20 or so people into writing good DocBook 
in a matter of 1 to 2 weeks.

We also need "local" system documentation in which a wiki cannot fix. We have 
talked about using a wiki not only in other projects but also with KDE, for a 
greater part of 5 years. Some people tend to think it will help, and in some 
cases it could help, but those cases did not outweigh the main features or 
requirements of a help system.

What we need to do is:
 * Fix KHelpCenter making it easier to use and much cleaner
 * Contributors to update current documentation

What we should look at doing is:
 * Work with GNOME and Freedesktop.org to create a unified Help/Doc System
 * Assist in the creation of a unified documentation application (Yelp & KHC)
 * Utilize a wiki in some instances to help collaborate on documentation
    * Need a wiki -> docbook tool (all out there are really bad)

Another thing I noticed in the original email or a response to Jonathan Jesse 
was to use a QA team to monitor wiki edits. Pretty much every project out there 
has done this in the past, and it ends up failing in the end because watching 
wiki changes and then ensuring their quality gets old very quick and tends to 
burn out even the hardest of hardcore open source contributors.

I really appreciate your willingness to help us and I hope you will continue 
doing so, however at this time I do not feel that a wiki is the best solution 
let alone a good solution. Harald and I have talked about this recently and he 
has a better understanding of what needs to be done. I will look at 
collaborating with GNOME and the Freedesktop.org specifications on the 
possibility of a unified help system, the correct way to move forward. Think 
about our biggest competitors, they use what is called "Topic Based Help" and 
this is something we (GNOME and KDE) need to look at doing.

-- 
Richard A. Johnson
nixternal at kubuntu.org
GPG Key: 0x2E2C0124
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part.
Url : http://mail.kde.org/pipermail/kde-doc-english/attachments/20080823/dd6f63d6/attachment.sig