[kde-doc-english] wiki

[Chusslove Illich]

> [: Yuri Chornoivan :]
> Feel free to send any documentation in this list (you can even write it on
> a peace of paper, scan, and email here). I promise you that I will convert
> your precious writing in these so-hard-to-write docbooks.

(I regularly complain about this, and now I cannot help but do it again :)

I very much like Albert's quip "The same reason we don't have our code in a
wiki", so how about a programmer saying to a would-be contributor who
complains that C++ is hard "Send in your code contribution in any
programming language (for which there are KDE bindings) and I will convert
it to C++"?

Ok, documentation is not code, and that's why your quote above seems
reasonable to you and other people, and mine code parallel is outright
ridiculous. But good part of the reason why it is ridiculous holds up for
the documentation as well. The most important part is maintainability; "you
write, I convert" is a recipe for having unmaintaned documentation.

Instead, the would-be documenter has to grasp the agreed upon format of the
documents, how they are written and processed, and integrated into the main
body. Only with this in hand can he reasonably contribute documentation. I
propose replacing "you write, I convert" policy with a nice tutorial
(perhaps this already exists?) on how to create documentation for a typical
KDE app. Short introduction into the format with pointers for more detailed
tutorials, how to get hold of existing documentation (location, VCS tool),
how to edit it (which editor, what are nice helpers in it for the particular
format), how to integrate it (send to whom, make patch, or commit). Then, if
a would-be documenter says "I've read it, but 'tis too hard!", end of story.

(Note: I'm not saying anything pro/against Docbook/wiki above, I'm just
commenting on the "you write, I convert" bit, whatever the format(s).)

-- 
Chusslove Illich (Часлав Илић)
-------------- 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/20100611/4baf34f9/attachment.sig