Improve documentation for System Agents and other account roles

Summary: Explain this stuff better and add some documentation links.

Test Plan: Read documentation, viewed account edit interfaces.

Reviewers: btrahan, vrana, jungejason

Reviewed By: btrahan

CC: aran

Maniphest Tasks: T834

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

src/docs/userguide/users.diviner

@@ -0,0 +1,64 @@
+@title User Guide: Account Roles
+@group userguide
+
+Describes account roles like "Administrator", "Disabled" and "System Agent".
+
+= Overview =
+
+When you create a user account, you can set roles like "Administrator",
+"Disabled" or "System Agent". This document explains what these roles mean.
+
+= Administrators =
+
+**Administrators** are normal users with extra capabilities. They have access
+to some tools and workflows that normal users don't, which they can use to
+debug and configure Phabricator. For example, they have access to:
+
+  - **Account Management**: The primary function of administrators is adding,
+    disabling, and managing user accounts. Administrators can create and edit
+    accounts and view access logs.
+  - **MetaMTA**: Administrators can send test email via MetaMTA. This isn't
+    available to normal users to prevent Phabricator from serving as a partially
+    open relay if used by open source projects.
+  - **Repositories**: Administrators can configure repositories. This isn't
+    normally available because it is specialized and complicated to configure.
+
+Administrators have a few other minor capabilities in other tools. When you are
+in an administrative interface, the menu bar is red.
+
+Administrators are **not** in complete control of the system. Administrators
+**can not** login as other users or act on behalf of other users. Administrators
+**can not** bypass object privacy policies.
+
+NOTE: Administrators currently //can// act on behalf of other users via Conduit.
+This will be locked down at some point.
+
+= System Agents =
+
+**System Agents** are accounts for bots and scripts which need to interface
+with the system but are not regular users. Generally, when you write scripts
+that use Conduit (like the IRC bot), you should create a System Agent account
+for them. System agents:
+
+  - **can not login** (they //can// access API methods via Conduit);
+  - **can not review diffs or own tasks**;
+  - **do not appear in CC tokenzers**.
+
+= Disabled Users =
+
+**Disabled Users** are accounts that are no longer active. Generally, when
+someone leaves a project (e.g., leaves your company, or their internship or
+contract ends) you should disable their account to terminate their access to the
+system. Disabled users:
+
+  - **can not login**;
+  - **can not access Conduit**;
+  - **do not receive email**;
+  - **do not appear in owner/reviewer/CC tokenizers**.
+
+Users can only be disabled (not deleted) because there are a number of workflows
+that don't make sense if their account is completely deleted, like: finding old
+revisions or tasks that they were responsible for (so you can get someone else
+to take care of them); identifying them as the author of their changes; and
+restoring all their data if they rejoin the project (e.g., they are later
+re-hired, maybe as a full time employee after an internship).