Lateral Opinion

There are some problems with some of the KDE apps docs. The biggest are:

Superficial:

They explain too broadly, not covering any specific details.

Uneven:

They explain some things in great detail and others not at all. For example, the kcalc docs explain what the lsh operator is. They don't explain what the M+/M-/C/CE buttons do.

Unfocused:

Being uneven is right, as long as what you don't exmplain is obvious (for example, not explaining the button 9 is good).

These problems are common to almost any technical document, and they are not easily fixed. In fact, the only known fix is having a very good technical writer, and a very good technical editor.

Sadly, those are very hard to find. And usually they won't do it for free.

So, here's a proposal for a solution that may make things easier for KDE4.

Open source the docs

Oh, sure, they are open source now. Anyone can hack them. As long as he knows how to get to their source code, which is in docbook.

I understand the docs team is willing to take plain text submissions and format them accordingly, but you can't quite figure that out from the docs themselves.

Even then, the barrier to entry is high, you have to write your explanation, send it through channels, and noone can see it until next release.

My proposal is to integrate in the KDE help viewer a limited wiki-like capability.

The user would have a "annotate this page" prominently displayed somewhere. And he could use that to attach annotations that should be clearly visible on the docs.

And, most importantly, he should be offered a chance to share those annotations, which would be uploaded to a wiki-like system. Said system would be moderated by the current docs team people, who could approve of them.

Then, the doc viewer should also have a feature to update the docs for a version, downloading new pages and annotations from that same system, completing the feedback loop.

Said annotations would then be shown along the docs, and could even be marked as "tips" which would be added to the tip-of-the-day system.

Should be a bit of work, but the KDE hackers are more than up to it, I'm sure :-)