[Kde-pim] How can we improve Akonadi documentation?

[Gregory Schlomoff]

Hello,

Well, persistance paid off. With the help of the people on #akonadi and
#kde-windows, I fixed all my problems, and I finally have a working build of
qt, dbus, kdelibs, kdepimlibs, akonadi & al. on my windows machine. (I was
doing a few mistakes, the main one being to mix kde libs compiled in Release
mode with my own code in Debug mode)

That's the good part.

Now, the not so good part: I am now trying to actually use Akonadi, and the
documentation isn't very helpful. I would actually go as far as to say it's
developer-adverse, in some (hopefully rare) cases.

I've spent a few hours trying to get the example on the ItemCreateJob
reference working (
http://api.kde.org/4.x-api/kdepimlibs-apidocs/akonadi/html/classAkonadi_1_1ItemCreateJob.html).
No matter what I'd try, it would not work. Out of frustration, I started
looking at random pages on the Akonadi doc, and finally found this:

Examples in the ItemCreateJob docs (and maybe others) operate on items in
> the root collection which does not work at all


(from: http://techbase.kde.org/Projects/PIM/Akonadi )

I guess you can imagine how I felt after reading this... It's like "WTF
don't you at the *very* *very* least put a single comment in your example
source if you know that it is not working, instead of leaving it as it is,
and documenting the problem on a random misc. wiki page?"

I understand that you:

1. Probably don't have enough resource to make a fully-covering,
high-quality doc
2. Are the main users of your library, so documentation isn't necessarily a
priority

But please, if Akonadi is meant to be a public API, think of the developers.
Think of the children :)

So what can we do to improve the quality of the documentation?

Cheers,

Greg
_______________________________________________
KDE PIM mailing list kde-pim at kde.org
https://mail.kde.org/mailman/listinfo/kde-pim
KDE PIM home page at http://pim.kde.org/