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

[Chusslove Illich]

> [: Albert Astals Cid :]
> [...] 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) [...]

Well, that is an elephant in the room. I too suspect that some simply don't
like writing *and* maintaining documentation, so that no technical
foundation will help there, and then "Docbook bad" serves as self-
justification. But, I also know for a fact that there are people who do like
to maintain documentation but hate Docbook. So I simply propose that people
experiment with formats, so long as they keep documentation tight to their
code, inside repository. From the i18n side, I will rather myself work to
support translation of these new formats as they come by, than waste time
translating outdated and information-free[1] Docbook.

I should also probably mention that I too tried with wiki, and had an
opposite experience to what some people in this thread report. I thought,
well this wiki is a bit too visual for my taste and maybe a bit too HTML
centric, but lets give it a shot, maybe it would even induce some serious
cooperation. The cooperation thing never happened, and for me personally it
was exceedingly problematic to keep wiki pages in sync with code changes. I
was forgetting what's where, forgetting that something even exists, and I
couldn't use mighty search facilities (a.k.a. "grep") to check for that. So,
after a few years, I folded everything to single in-repository directory (in
Docbook). Now I keep documentation files always open in my Kate session for
the given project, right there in my face, and commits/merges of user-
visible changes always go in with the documentation update.

[1] "Information-free" I consider when documentation states no more than
what is stated by tooltips and whatsthis within the program. Please, please,
drop the requirement that every KDE SC program should have documentation. If
a program does not have documenation, and you the willing documentation
writer don't use it on a regular basis, just ignore it.

-- 
Chusslove Illich (Часлав Илић)
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 197 bytes
Desc: This is a digitally signed message part.
URL: <http://mail.kde.org/pipermail/kde-core-devel/attachments/20120703/285551bb/attachment.sig>