About Writing Documentation in KDE

[Yuri Chornoivan]

Mon, 02 Jul 2012 12:00:05 +0300 було написано Anne Wilson <annew at kde.org>:

> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> - -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
>
> On 02/07/12 09:00, Albert Astals Cid wrote:
>> El Dilluns, 2 de juliol de 2012, a les 01:45:14, Dominik Haumann va
>> escriure:
>>> Hi everyone,
>>>
>>> so let's sum up and get back to arguments.
>>>
>>> 1. Versioning for our KDE SC Releases It was mentioned that a
>>> wiki automatically provides versioning. However, what is
>>> completely not covered, yet, is the fact that we have different
>>> KDE SC releases. There is not 'branching' support for the wikis,
>>>  so you have to create different wiki pages, copying the entire
>>> content for each release.
>>>
>>> Contrary, this is completely covered by maintaining the
>>> documentation in the respective modules. This is also the reason
>>>  why we have documentation freezes (even one of the last freezes
>>>  [2]).
>>>
>>> 2. Documentation Team We have a documentation team, even for each
>>> of our supported languages. They coordinate on kde-i18n-doc [1],
>>> and Burkhard offered support several times, saying that if you do
>>> not want to write docbook, the documentation team will do the
>>> markup, they even write the documentation for you to some
>>> extent.
>>>
>>> 3. Consistency The documentation team makes sure the
>>> documentation sticks to the documentation guidelines for
>>> consistency (example: folder vs. directory). This was mentioned
>>> in the past several times on the mailing lists. Again, a
>>> statement of the documentation team is very important here.
>>>
>>> 4. Getting Help Please ask the documentation team for their
>>> opinion, before raising critics the way it currently works. Maybe
>>> it works for a lot of other projects perfectly fine. In the
>>> thread it was mentioned, that some people do not even know where
>>> the documentation resides (maybe this is due to the partial
>>> transition to git). A simple solution is to ask the documentation
>>> team (or Burkhard) where to find the documentation. I'm pretty
>>> sure the documentation team has really valuable information.
>>> Please do not ignore them.
>>>
>>> 5. A Simple Solution: Possibility of a Combination If docbook
>>> really does not work for your project, it's fine to have an
>>> additional entry in the Help menu that links to the "Community
>>> Documentation" on UserBase. There is room for both, docbook and
>>> the wiki.
>>>
>>> 6. Respect [4]: Akademy Award In 2010, Burkhard Lück got the
>>> Akademy Award for his fantastic work on improving the state of
>>> the KDE documentation [3], supported by the entire KDE community.
>>> Now, two years later, this thread on kcd acts as if the
>>> documentation completely sucks. Guys, it does not. Really. Please
>>> think about this for a minute... (see 5.)
>>>
>>> That's all.
>>
>> 7. The one that does the work decides I also want to note that
>> developers that do not write documentation in docbook and that do
>> not translate manuals are suggesting to switch to wiki (even if
>> they agree they won't write documentation anyway) while people
>> doing documentation and translation of manuals (Yuri, Burkhard,
>> Chusslove) say the current workflow is good. Seems like the "The
>> one that does the work decides" is being ingored.
>>
>
> This is not in any way dissing the work of those that put in much
> effort but -
>
> If the current system is so good, can someone please explain to me why
> distros ship with docbook help pages that were written years ago and
> not updated since?
>
> Anne

The current system has many shortcomings that were pointed out by many  
people in this thread.

But these shortcomings are not the reason to fight current offline system.

The better availability, fast editing capabilities, good translation  
support of current UserBase have not produce many high quality handbooks  
yet. Some sort of recipes, good tutorials, but there are only a few  
handbooks... All converted docbooks have links to corresponding UserBase  
pages, so there is nothing to prevent users from fixing them.

Hence, we have to admit that the main problem is the lack of KDE  
documenters themselves, not the format or the place where the docs are  
stored.

Now, we can live with both systems. If developers want their documentation  
to be based on UserBase pages, it's OK. If they want to have tutorials  
(videos, screencastings) on UserBase, it's OK too. Do not want to have  
UserBase handbook? Even this is OK. ;)

What is the reason to push documentation where it slowly dies without any  
attention (like rekonq docs, for example)? Let developers to decide  
themselves what is better: fixed handbook in their repo, contacts with  
Documentation team and link to index.html in .desktop file or link to  
http://userbase.kde.org/Special:MyLanguage/APP_NAME/Handbook (to have  
localization support, not just like it was done in Krita) and self-written  
or user-written documentation.

If some user havs a concern about current state of offline documentation,  
there is a link to complain at the bottom of each of its pages. If some  
users file a bug about lack of offline copy or offline translation we can  
provide them if UserBase handbook of the proper quality exists. ;)

They can also choose the way with no documentation at all (Calligra Karbon  
and Flow, Muon, Apper, KDE Color Managers, new Kubuntu Print Manager, etc.)

And as a final note, some KDE application have copyrights of 2005 year and  
that does not prevent them to work properly (as in 2005) if they were  
written by talented KDE developers. ;)

Yuri