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

[Albert Astals Cid]

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.

Cheers,
  Albert

> 
> 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_Decem
> ber_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/