Rationalise lists of built-in groups and their capabilities into one correct list. r=dylan

2 files changed, 60 insertions, 79 deletions

diff --git a/docs/en/rst/administering/users.rst b/docs/en/rst/administering/users.rst
index 7d5b33399..3e3ab207f 100644
--- a/docs/en/rst/administering/users.rst
+++ b/docs/en/rst/administering/users.rst
@@ -56,11 +56,12 @@ fields:
 - *Email Address*:
   This is the user's full email address. Unless you turn off the
   :param:`allowemailchange` parameter, users can change their
-  login names themselves (to any valid email address).
+  email address to any other valid email address they control.
 
 - *Login Name*:
-  This is the user's login name, if it is (or can be) different from their email
-  address (i.e. if the "use_email_as_login" parameter is switched off).
+  If the "use_email_as_login" parameter is switched off, the user also has
+  a separate login name, which is (or can be) different from their email
+  address.
 
 - *Real Name*: The user's real name. Note that
   Bugzilla does not require this to create an account.
@@ -71,9 +72,9 @@ fields:
   If you want to disable an account, see Disable Text below.
 
 - *Bugmail Disabled*:
-  Mark this checkbox to disable bugmail and whinemail completely
-  for this account. This checkbox replaces the data/nomail file
-  which existed in older versions of Bugzilla.
+  Check this checkbox to disable bugmail and whinemail completely
+  for this account. Note that this does not prevent the user logging in or
+  taking any other action.
 
 - *Disable Text*:
   If you type anything in this box, including just a space, the
@@ -97,54 +98,15 @@ fields:
   .. warning:: Don't disable all the administrator accounts!
 
 - *<groupname>*:
-  If you have created some groups, e.g. "securitysensitive", then
-  checkboxes will appear here to allow you to add users to, or
-  remove them from, these groups. The first checkbox gives the
+  Checkboxes will appear here to allow you to add users to, or
+  remove them from, permission groups. The first checkbox gives the
   user the ability to add and remove other users as members of
-  this group. The second checkbox adds the user himself as a member
+  this group. The second checkbox makes the user himself a member
   of the group.
 
-- *canconfirm*:
-  This field is only used if you have enabled the "unconfirmed"
-  status. If you enable this for a user,
-  that user can then move bugs from "Unconfirmed" to a "Confirmed"
-  status (e.g.: "New" status).
-
-- *creategroups*:
-  This option will allow a user to create and destroy groups in
-  Bugzilla.
-
-- *editbugs*:
-  Unless a user has this bit set, they can only edit those bugs
-  for which they are the assignee or the reporter. Even if this
-  option is unchecked, users can still add comments to bugs.
-
-- *editcomponents*:
-  This flag allows a user to create new products and components,
-  modify existing products and components, and destroy those that have
-  no bugs associated with them. If a product or component has bugs
-  associated with it, those bugs must be moved to a different product
-  or component before Bugzilla will allow them to be destroyed.
-
-- *editkeywords*:
-  If you use Bugzilla's keyword functionality, enabling this
-  feature allows a user to create and destroy keywords. A keyword
-  must be removed from any bugs upon which it is currently set
-  before it can be destroyed.
-
-- *editusers*:
-  This flag allows a user to do what you're doing right now: edit
-  other users. This will allow those with the right to do so to
-  remove administrator privileges from other users or grant them to
-  themselves. Enable with care.
-
-- *tweakparams*:
-  This flag allows a user to change Bugzilla's Params
-  (using :file:`editparams.cgi`.)
-
-- *<productname>*:
-  This allows an administrator to specify the products
-  in which a user can see bugs.
+  Bugzilla has a number of built-in groups. For the full set of groups and their
+  capabilities, see :ref:`permissions`. This list will also contain any groups
+  you have created.
 
 .. _createnewusers:
 
diff --git a/docs/en/rst/using/preferences.rst b/docs/en/rst/using/preferences.rst
index d61dc4f8a..f0ffc5c1a 100644
--- a/docs/en/rst/using/preferences.rst
+++ b/docs/en/rst/using/preferences.rst
@@ -144,52 +144,71 @@ API key' section of the page.
 Permissions
 ===========
 
-This is a purely informative page which outlines your current
+This is an informational page which outlines your current
 permissions on this installation of Bugzilla.
 
-A complete list of permissions in a default install of Bugzilla is below.
-Your administrator may have defined other permissions. Only users with
-*editusers* privileges can change the permissions of other users.
+A complete list of available permissions in a default install of Bugzilla is
+below. Your administrator may have defined other permissions. Only users with
+the *editusers* permission can change the permissions of other users.
 
 admin
-    Indicates user is an Administrator.
+    User is an administrator, which (in normal circumstances) means they can
+    do anything.
 
-bz_canusewhineatothers
-    Indicates user can configure whine reports for other users.
-
-bz_canusewhines
-    Indicates user can configure whine reports for self.
-
-bz_quip_moderators
-    Indicates user can moderate quips.
+tweakparams
+    Permits user to change administration :ref:`Parameters <parameters>`, and
+    to enable, disable and change the default value of
+    :ref:`General Preferences <generalpreferences>`.
 
 bz_sudoers
-    Indicates user can perform actions as other users.
+    Permits user to impersonate and perform actions as other users. This is
+    useful for admins to reproduce problems with Bugzilla, such as permissions
+    problems, that other users see.
 
 bz_sudo_protect
-    Indicates user cannot be impersonated by other users.
-
-canconfirm
-    Indicates user can confirm a bug or mark it a duplicate.
+    Indicates user cannot be impersonated by other users who have the
+    *bz_sudoers* permission.
 
 creategroups
-    Indicates user can create and destroy groups.
-
-editbugs
-    Indicates user can edit all bug fields.
+    Permits user to create, delete and edit permission groups.
 
 editclassifications
-    Indicates user can create, destroy and edit classifications.
+    Permits user to create, delete and edit classifications.
 
 editcomponents
-    Indicates user can create, destroy and edit products, components,
+    Permits user to create, delete and edit products, components,
     versions, milestones and flag types.
 
+    This capability can also be given on a per-product basis.
+
 editkeywords
-    Indicates user can create, destroy and edit keywords.
+    Permits user to create, delete and edit keywords.
 
 editusers
-    Indicates user can create, disable and edit users.
+    Permits user to create, disable and edit users.
 
-tweakparams
-    Indicates user can change :ref:`Parameters <parameters>`.
+canconfirm
+    Permits user to confirm a bug (move it from UNCONFIRMED to
+    another status).
+
+    This permission is only used if you are using the UNCONFIRMED status in
+    any products. The *editbugs* permission implies this permission.
+
+    This capability can also be given on a per-product basis.
+
+editbugs
+    Permits user to edit all fields on a bug. Without this permission, users
+    can only edit bugs where they are the reporter or the assignee, or add
+    comments.
+
+    This capability can also be given on a per-product basis.
+
+bz_canusewhines
+    Permits user to configure whine reports to be sent to themselves.
+
+bz_canusewhineatothers
+    Permits user to configure whine reports to be sent to other users.
+
+bz_quip_moderators
+    Permits user to moderate the list of quips (pithy sayings at the top of
+    bug lists).