About Writing Documentation in KDE (was: Using userbase for manuals)

[Dominik Haumann]

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.

Thanks,
Dominik

[1] https://mail.kde.org/mailman/listinfo/kde-i18n-doc/
[2] http://techbase.kde.org/Schedules/KDE4/4.8_Release_Schedule#Monday.2C_December_19.2C_2011:_KDE_SC_4.8_Documentation_Freeze
[3] http://dot.kde.org/2010/07/05/akademy-day-2
[4] http://www.kde.org/code-of-conduct/