About Writing Documentation in KDE

[Christoph Cullmann]

> El Dilluns, 2 de juliol de 2012, a les 10:00:05, Anne Wilson va
> escriure:
> > -----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?
> 
> Maybe they don't need to be updated?
> http://techbase.kde.org/Projects/Documentation/KDE4_%28health_table%29
> looks quite green to me
Yeah, and, just as an other example, look at the state for Kate docs:

State of manual:

The manual is really nice, Burkhard and Hollingsworth really keep the manual up-to-date
and complete. Thanks to the brilliant work of our translators, we even get this translated!
Thanks to all for that massive work

State of wiki:

Look at http://userbase.kde.org/Kate
The user base page about Kate is just a small skeleton, even no german translation is around.

But, I agree, that it might be nice to have some predefined link in the menu to go to the matching userbase
page for the app, if available, in the right language, to allow the user to discover this additional information
more easily

Greetings
Christoph

-- 
-------------------------------------- Christoph Cullmann ---------
AbsInt Angewandte Informatik GmbH      Email: cullmann at AbsInt.com
Science Park 1                         Tel:   +49-681-38360-22
66123 Saarbrücken                      Fax:   +49-681-38360-20
GERMANY                                WWW:   http://www.AbsInt.com
--------------------------------------------------------------------
Geschäftsführung: Dr.-Ing. Christian Ferdinand
Eingetragen im Handelsregister des Amtsgerichts Saarbrücken, HRB 11234