About Writing Documentation in KDE

[Anne Wilson]

-----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

- -----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-----