[kde-doc-english] wiki

[Yuri Chornoivan]

--- Оригінальне повідомлення ---
Від кого: Chusslove Illich <caslav.ilic at gmx.net>
Кому: For people writing documentation for KDE <kde-doc-english at kde.org>
Дата: 11 червня, 11:12:55
Тема: Re: [kde-doc-english] wiki

> > [: 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 unmaintained documentation.

Well, all those previous authors know how to write docbooks. In fact, I have learned the basics in a few hours. Today's authors do not want to learn XML? They want to write unstructured philosophical content on wiki? No problem.

Who will maintain the documentation and where it will happen? It does not matter for me. New format needed? So where is the guarantee that after the first "gold rush" we will not have "deep freeze"? Just look at the UB commits curves. There was the weeks when you can change three letters and be the king of the commits! I know, any result is better than no results at all. Even now developers prefer blog about something than write in this new shiny-so-easy-to-use wiki. I see at least ten wikis (top-ten distributions wikis among them) without any useful content, broken links and no contributors. Today's customers community prefer rants with no suggestions or suggestions like "let's change everything and see".

<ironymode>
But please do not talk that this was because the docbook XML and strange wiki formatting. Maybe time is changing? So lets convert khelpcenter in a nice knowledgebase plasmoid with google search. Bugzilla is also hard to use for developers. Lets change it to another plasmoid with google search for bugs.
</ironymode>

And do not call the documentation this:

<almost quote>
After the program started you will see this:
<screenshot>
foo.jpg
</screenshot>
To change the settings of the application click "Settings". You will see this:
<screenshot>
bar.jpg
</screenshot>
Click "Preference1" to change Preference1 and you are done.
</almost quote>

I am tired to translate these needless self-evident truisms of wiki along with marketing things.

What is the harm if I convert documentation to docbook? Some prefer documentation in MS Word DOC. Some might say "Give me the man!" Some might say "I want Mallard with the perfect documentation like this [1]". And some might say "I want it in Ukrainian!" It's just a matter of preferences. Should I say them, e.g. "Translate it by yourself or it will be unmaintainable!"?

If the documentation is worth to be read, you will always find someone to convert it in a proper format. There is not unmaintainability at all.

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

And what would we do if nothing changes? If developer will blog "Personally, I do not like <the new format>, as I do not have time to learn it and read all this stupid Documentation Team manuals. Please read my nice blog, I documented my program here!"

What would we do if tomorrow someone says "Wiki is old, let's video all the things and put it on KDE videoblog!"?

It takes few hours to convert to the docbook; it takes ten years to build the tradition.

> 
> (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 (Часлав Илић)
> 

[1] http://library.gnome.org/users/gcalctool/stable/factorial.html.en