About Writing Documentation in KDE

[Albert Astals Cid]

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

Cheers,
  Albert

> 
> Anne
> 
> - -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.12 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
> 
> iEYEARECAAYFAk/xYsQACgkQj93fyh4cnBfP1gCfbC0VcQPgK5yfwnjeNNw78yFG
> GV8An06jkszrvKXT2Bvrcx9BSyHdQ0jg
> =b094
> - -----END PGP SIGNATURE-----
> -----BEGIN PGP SIGNATURE-----
> Version: GnuPG v1.4.12 (GNU/Linux)
> Comment: Using GnuPG with Mozilla - http://enigmail.mozdev.org/
> 
> iEYEARECAAYFAk/xYxMACgkQj93fyh4cnBf1XwCgiObTExc3vZ/kbGdGuE3COU8g
> BV0An3OTxK1+ktasLoKbiyFw9lXtTbdk
> =fHkk
> -----END PGP SIGNATURE-----