Fix many lies in the "User Roles" document

Summary: Fixes T3047. Update this document and remove some lies ("menu bar is read in admin interfaces"!!!!).

Test Plan:
  - Read text.
  - Searched for "System Agent" in the UI and replaced it with "bot" or "bot/script" or similar.

Reviewers: chad, btrahan

Reviewed By: btrahan

Subscribers: epriestley

Maniphest Tasks: T3047

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

scripts/user/account_admin.php

@@ -123,7 +123,7 @@ if (strlen($password)) {
 
 $is_system_agent = $user->getIsSystemAgent();
 $set_system_agent = phutil_console_confirm(
-  'Should this user be a system agent?',
+  'Is this user a bot/script?',
   $default_no = !$is_system_agent);
 
 $verify_email = null;
@@ -163,7 +163,7 @@ printf($tpl, 'Password', null,
 
 printf(
   $tpl,
-  'System Agent',
+  'Bot/Script',
   $original->getIsSystemAgent() ? 'Y' : 'N',
   $set_system_agent ? 'Y' : 'N');
 

src/applications/people/controller/PhabricatorPeopleListController.php

@@ -81,7 +81,7 @@ final class PhabricatorPeopleListController extends PhabricatorPeopleController
       }
 
       if ($user->getIsSystemAgent()) {
-        $item->addIcon('computer', pht('System Agent'));
+        $item->addIcon('computer', pht('Bot/Script'));
       }
 
       if ($viewer->getIsAdmin()) {

src/applications/people/query/PhabricatorPeopleSearchEngine.php

@@ -108,7 +108,7 @@ final class PhabricatorPeopleSearchEngine
           ->addCheckbox(
             'isAdmin',
             1,
-            pht('Show only Administrators.'),
+            pht('Show only administrators.'),
             $is_admin)
           ->addCheckbox(
             'isDisabled',
@@ -118,7 +118,7 @@ final class PhabricatorPeopleSearchEngine
           ->addCheckbox(
             'isSystemAgent',
             1,
-            pht('Show only System Agents.'),
+            pht('Show only bots.'),
             $is_system_agent)
           ->addCheckbox(
             'needsApproval',

src/applications/typeahead/controller/PhabricatorTypeaheadCommonDatasourceController.php

@@ -185,7 +185,7 @@ final class PhabricatorTypeaheadCommonDatasourceController
         if ($user->getIsDisabled()) {
           $closed = pht('Disabled');
         } else if ($user->getIsSystemAgent()) {
-          $closed = pht('System Agent');
+          $closed = pht('Bot/Script');
         }
 
         $result = id(new PhabricatorTypeaheadResult())

src/docs/tech/chatbot.diviner

@@ -63,7 +63,7 @@ servers and in different languages.
 To allow the bot to access Conduit, you need to create a user that it can login
 with. To do this, login to Phabricator as an administrator and go to
 ##People -> Create New Account##. Create a new account and flag them as a
-"System Agent". Then in your configuration file, set these parameters:
+"Bot/Script". Then in your configuration file, set these parameters:
 
   - ##conduit.uri## The URI for your Phabricator install, like
     ##http://phabricator.example.com/##

src/docs/user/userguide/users.diviner

@@ -1,50 +1,59 @@
 @title User Guide: Account Roles
 @group userguide
 
-Describes account roles like "Administrator", "Disabled" and "System Agent".
+Describes account roles like "Administrator", "Disabled" and "Bot".
 
 = Overview =
 
 When you create a user account, you can set roles like "Administrator",
-"Disabled" or "System Agent". This document explains what these roles mean.
+"Disabled" or "Bot". This document explains what these roles mean.
 
 = Administrators =
 
-**Administrators** are normal users with extra capabilities. They have access
+**Administrators** are normal users with a few extra capabilities. Their primary
-to some tools and workflows that normal users don't, which they can use to
+role is to keep things running smoothly, and they are not all-powerful. In
-debug and configure Phabricator. For example, they have access to:
+Phabricator, administrators are more like //janitors//.
 
-  - **Account Management**: The primary function of administrators is adding,
+Administrators can create, delete, enable, disable, and approve user accounts.
-    disabling, and managing user accounts. Administrators can create and edit
+Various applications have a few other capabilities which are reserved for
-    accounts and view access logs.
+administrators by default, but these can be changed to provide access to more
-  - **Repositories**: Administrators can configure repositories. This isn't
+or fewer users.
-    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** login as other users or act on behalf of other users. They can not
-**can not** bypass object privacy policies.
+destroy data or make changes without leaving an audit trail. Administrators also
+can not bypass object privacy policies.
+
+Limiting the power of administrators means that administrators can't abuse
+their power (they have very little power to abuse), a malicious administrator
+can't do much damage, and an attacker who compromises an administrator account
+is limited in what they can accomplish.
 
 NOTE: Administrators currently //can// act on behalf of other users via Conduit.
 This will be locked down at some point.
 
-= System Agents =
+= Bot/Script Accounts =
 
-**System Agents** are accounts for bots and scripts which need to interface
+**Bot/Script** accounts are accounts for bots and scripts which need to
-with the system but are not regular users. Generally, when you write scripts
+interface with the system, but are not regular users. Generally, when you write
-that use Conduit (like the IRC bot), you should create a System Agent account
+scripts that use Conduit (like the IRC bot), you should create a Bot/Script
-for them. System agents:
+account for them.
 
-  - **can not login** (they //can// access API methods via Conduit);
+These accounts were previously called "System Agents", but were renamed to make
-  - **can not review diffs or own tasks**;
+things more clear.
-  - **do not appear in CC tokenzers**.
 
-Currently, the **System Agent** role for an account can not be changed after the
+The **Bot/Script** role for an account can not be changed after the account is
-account is created. This prevents administrators form changing a normal user
+created. This prevents administrators form changing a normal user into a bot,
-into a system agent, retrieving their Conduit certificate, and then changing
+retrieving their Conduit certificate, and then changing them back (which
-them back (which would allow administrators to gain other users' credentials).
+would allow administrators to gain other users' credentials).
+
+**Bot/Script** accounts differ from normal accounts in that:
+
+  - administrators can access them, edit settings, and retrieve credentials;
+  - they do not receive email;
+  - they appear with lower precedence in the UI when selecting users, with
+    a "Bot" note (because i t usually does not make sense to, for example,
+    assign a task to a bot).
 
 = Disabled Users =
 
@@ -53,14 +62,14 @@ 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 login;
-  - **can not access Conduit**;
+  - can not access Conduit;
-  - **do not receive email**;
+  - do not receive email; and
-  - **do not appear in owner/reviewer/CC tokenizers**.
+  - appear with lower precedence in the UI when selecting users, with a
+    "Disabled" note (because it usually does not make sense to, for example,
+    assign a task to a disabled user).
 
-Users can only be disabled (not deleted) because there are a number of workflows
+While users can also be deleted, it is strongly recommended that you disable
-that don't make sense if their account is completely deleted, like: finding old
+them instead if they interacted with any objects in the system. If you delete a
-revisions or tasks that they were responsible for (so you can get someone else
+user entirely, you won't be able to find things they used to own or restore
-to take care of them); identifying them as the author of their changes; and
+their data later if they rejoin the project.
-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).