I'll have to say that I don't find PolicyKit's documentation very good. I don't know how it is for a developer, but for me as a long-time Unix admin it was frustrating when I had to delve into it a few weeks ago for the first time.
The document linked by you was one of the 1st that I read, btw. It's not that I didn't understand what PolicyKit was supposed to be doing, that was quite clear from the start. And not even that I couldn't read the config files -- while being rather chatty, they were understandable.
Where I didn't succeed, is finding concise information about the overall architecture: how PolicyKit / ConsoleKit / HAL / D-Bus / pam / login processes, both X and console, are *supposed* to work together. That would have delivered pointers to information sources that could have answered questions like Where are the names in the PolicyKit XML files from? Which possible names exist on a given system? Which daemons are started and by whom? What are common PolicyKit authorizations, since it is all about policy and nothing about content? The output of polkit-auth --show-obtainable is not sufficient, IMHO. E.g., I'd need to know what org.freedesktop.hal.lock is, and googling it on site:freedesktop.org does _not_ provide an adequate answer, at least not for me. (And yes, I've read http://people.freedesktop.org/~david/hal-spec/hal-spec.html.)
It was not easy to find the answers to such questions in reasonable time frames because the overall structure had to be laborously reverse engineered by yours humbly. Well, maybe my Google foo may simply be not good enough.