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/applications/people/controller/edit/PhabricatorPeopleEditController.php

@@ -243,7 +243,8 @@ final class PhabricatorPeopleEditController
           ->setName('email')
           ->setDisabled($is_immutable)
           ->setValue($user->getEmail())
-          ->setError($e_email));
+          ->setError($e_email))
+      ->appendChild($this->getRoleInstructions());
 
     if (!$user->getID()) {
       $form
@@ -367,6 +368,7 @@ final class PhabricatorPeopleEditController
     }
 
     $form
+      ->appendChild($this->getRoleInstructions())
       ->appendChild(
         id(new AphrontFormCheckboxControl())
           ->addCheckbox(
@@ -440,4 +442,21 @@ final class PhabricatorPeopleEditController
     return array($panel);
   }
 
+  private function getRoleInstructions() {
+    $roles_link = phutil_render_tag(
+      'a',
+      array(
+        'href'   => PhabricatorEnv::getDoclink(
+          'article/User_Guide:_Account_Roles.html'),
+        'target' => '_blank',
+      ),
+      'User Guide: Account Roles');
+
+    return
+      '<p class="aphront-form-instructions">'.
+        'For a detailed explanation of account roles, see '.
+        $roles_link.'.'.
+      '</p>';
+  }
+
 }

src/applications/people/controller/edit/__init__.php

@@ -11,6 +11,7 @@ phutil_require_module('phabricator', 'aphront/response/redirect');
 phutil_require_module('phabricator', 'applications/people/controller/base');
 phutil_require_module('phabricator', 'applications/people/storage/log');
 phutil_require_module('phabricator', 'applications/people/storage/user');
+phutil_require_module('phabricator', 'infrastructure/env');
 phutil_require_module('phabricator', 'view/form/base');
 phutil_require_module('phabricator', 'view/form/control/checkbox');
 phutil_require_module('phabricator', 'view/form/control/select');

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).