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

[Stephen Kelly]

Gregory Schlomoff wrote:

> 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 had some trouble with it too when I started out.

I started writing some new documentation here:

http://api.kde.org/playground-api/pim-
apidocs/akonadi/akonadi_next/html/index.html

But it seems I didn't merge it into the existing docs when I moved the 
entitytreemodel. I think it has useful information in it, though some of the 
classes referenced there have since been renamed or moved. I'll try to find 
time to merge that into the main docs some time soon.

I would also strongly encourage you to help write the docs you are missing 
by asking the questions and the rest of us giving the answers. Many of us 
are too deep into it that we don't see the high-level overview issues as you 
say.


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

Fixed:

http://websvn.kde.org/?view=revision&revision=1175579

Just so I don't create more confusion, what remains is valid use of 
Collection::root(). Try:

KDE/kdepimlibs/akonadi{trunk}$ find -name "*.h" | xargs grep 
"Collection::root"


> 
> 
> 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 think the wiki page is a list of issues that need to be solved, such as 
updating the documentation where these issues remain.

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

I think asking it would help if people like yourself would ask the highlevel 
questions here or on IRC and maintain a list of answers or a getting started 
page. In many cases we don't even know the questions. 

Also, please don't spend hours confused about something :). Ask here or on 
irc within an hour instead of being confused. There's a lot of difficult 
things in the API because it's all asynchronous, a bit abstract, there's 
several channels of communication like imap/dbus, heavily relies on 
platformy/funny things like mimetypes and desktop files etc, and it can be 
hard to know where standards end and extensions begin. Everyone hits a few 
brick walls at the start.

All the best,

Steve.


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