As mentioned above, have a look at the polkit man page. PolicyKit is actually very well documented. The main polkit man page describes the architecture, gives summaries and links to the tools (including pkaction) and examples for configuring policy. It even has ascii screenshots. To be honest, I haven't come across many projects with better documentation.