Scattered API documentation

[Steve Dodier-Lazaro]

Hi,

I find it overly difficult to find the *right* documentation for the Zeitgeist DBus API or for libzeitgeist. I've broken down my rant into several points with fix ideas. The reason why I complain about this is that as a developer who's interested in using ZG, just writing up some basic hello world programs is hard not because the API is complicated but because I'm still not sure I have the good documentation for it...

1) Doc is hosted everywhere and nowhere
Problem: often googling for a libzeitgeist function will return old docs hosted by actual developers of the project. For instance http://people.ubuntu.com/~manishsinha/zeitgeist/docs/. This is detrimental to the project as the real, regularly-built docs are harder to index and find through search engines.

Fix: take down all the unofficial docs. Host the docs properly on zeitgeist-project.org (see below) and nowhere else, and make sure to abundantly refer to the URL of the docs on Launchpad, developer blogs, etc.

2) Zeitgeist-project.org/docs could be improved
Problem a: there is no stable/current/latest URL to be sure to always reach the latest doc. That means engines pick up and reference (and serve) old URLs of versions of the lib that sticked around longest, and old URLS are propagated through blogs, etc.

Fix a: create a "current" or "stable" symlink to the latest doc on the website and keep it up to date, make sure to write a robots.txt file that forbids indexing URLs with version numbers so that these are no longer found by accident.

Problem b: http://zeitgeist-project.com/docs/ gives a 403, hence does not help to figure out what docs are available.

Fix b: instead, it should return a list of available documentations per version and per programming language.

3) Version numbers are pretty inconsistent
Problem: [steve@Alcaniz ~]$ pacman -Ss zeitgeist
extra/libqzeitgeist 0.8.0-3 [installed]
    A Qt interface to the Zeitgeist event tracking system
extra/libzeitgeist 0.3.18-4 [installed]
    Zeitgeist client library
extra/zeitgeist 0.9.14-1 [installed]
    Service logging user activities and events
community/activity-log-manager 0.9.7-1 [installed]
    A graphical user interface which lets you easily control what gets logged by
    Zeitgeist
community/gnome-activity-journal 0.8.0-7 [installed: 0.8.0-6]
    Tool for easily browsing and finding files on your computer using the
    Zeitgeist engine

That's 4 different version numbers for a single project where all packages depend on one another.

Consequence: http://eurion.net/zeitgeist/docs/0.8.2/dbus_api.html seems to be the latest API on eurion.net. Yet this is again another number, I would expect 0.3.18 or 0.9.7 (also funnily the page mentions that it's actually the 0.8.1.1 doc).

http://zeitgeist-project.com/docs/0.3.3/index.html#engine-documentation also seems to be the latest "Zeitgeist Doc" even though it's unclear from its title the documentation of *what* it is.

Fix: one single version number. Archive all the previously numbered doc in one place labelled "Archive" and reorganise the website so that people know if they're using the DBus doc, the C API, the Vala API, a general documentation on Zeitgeist's purpose and internals, etc. and so that people know what version of ZG AND libzg the doc refers to.

Why is it inconsistent to have several version numbers? API-wise the only thing that matters in a documentation is that you rewrite a function's doc when the API changes. And when the API changes you need to update most of the packages anyway since they use that very API! Hence it makes sense to bump their version number too and make sure that others know what you're serving them.

Thanks.