Update Herald docs

Summary:
Update the Herald documentation with information about global vs personal rules.

NOTE: Some of the features mentioned here don't exist yet (flags, delete rules), I'll add them before I land this.

Test Plan: Read documentation

Reviewers: jungejason, btrahan

Reviewed By: btrahan

CC: aran, epriestley

Differential Revision: https://secure.phabricator.com/D2031

src/docs/userguide/herald.diviner

@@ -5,10 +5,10 @@ Use Herald to get notified of changes you care about.
 
 = Overview =
 
-Herald allows you to write processing rules that take effect when objects are
-created or updated. For instance, you might want to get notified every time
-someone sends out a revision that affects some file you're interested in, even
-if they didn't add you as a reviewer.
+Herald allows you to write processing rules that take effect when objects (such
+as Differential revisions and commits) are created or updated. For instance, you
+might want to get notified every time someone sends out a revision that affects
+some file you're interested in, even if they didn't add you as a reviewer.
 
 Herald is less useful for small organizations (where everyone will generally
 know most of what's going on) but the usefulness of the application increases
@@ -16,6 +16,21 @@ as an organization scales. Once there is too much activity to keep track of it
 all, Herald allows you to filter it down so you're only notified of things you
 are interested in.
 
+= Global and Personal Rules =
+
+You can create two kinds of Herald rules, //global// and //personal//:
+
+  - **Personal Rules** are rules you own, but they can only affect you. Only
+    you can edit or delete personal rules, but their actions are limited to
+    adding you to CC, subscribing you, etc.
+  - **Global Rules** are rules everyone owns, and they can affect anything.
+    Anyone can edit or delete a global rule, and they can take any action,
+    including affecting projects and mailing lists.
+
+The general idea is to prevent individuals from controlling rules that affect
+shared resources, so if a rule needs to be updated it's not a big deal if the
+person who created it is on vacation.
+
 = Rules, Conditions and Actions =
 
 The best way to think of Herald is as a system similar to the mail rules you can
@@ -36,6 +51,28 @@ CC list.
 Now you'll automatically be added to CC any time alincoln creates a revision,
 and can keep an eye on what he's up to.
 
+= Available Actions =
+
+Herald rules can take a number of actions. Note that some actions are only
+available from Global rules, and others only from Personal rules. Additionally,
+not every action is available for every object type (for instance, you can not
+trigger an audit based on a Differential revision).
+
+  - **Add CC**: Add a user or mailing list to the CC list for the object. For
+    personal rules, you can only add yourself.
+  - **Remove CC**: Remove a user or mailing list from the CC list for the
+    object. For personal rules, you can only remove yourself.
+  - **Send an Email to**: Send one email, but don't subscribe to other updates.
+    For personal rules, you can only email yourself.
+  - **Trigger an Audit**: For commits, trigger an audit request for a project
+    or user. For personal rules, you can only trigger an audit request to
+    yourself.
+  - **Mark with flag**: Flag the object for later review. This action is only
+    available on personal rules. If an object already has a flag, this action
+    will not add another flag.
+  - **Do Nothing**: Don't do anything. This can be used to disable a rule
+    temporarily, or to create a rule for an "Another Herald rule" condition.
+
 = Testing Rules =
 
 When you've created a rule, use the "Test Console" to test it out. Enter a