Documentation updates for roles.

6 files changed, 40 insertions, 19 deletions

diff --git a/docs/_includes/admin-tasks-content.md b/docs/_includes/admin-tasks-content.md
index b62e9f531..3f18a00dc 100644
--- a/docs/_includes/admin-tasks-content.md
+++ b/docs/_includes/admin-tasks-content.md
@@ -468,7 +468,7 @@ To synchronise your records once you're back online, just visit any page on FixM
 
 #### Creating a staff account
 
-<span class="admin-task__permissions">Permissions required: User must be marked as staff; ‘Edit other users’ permissions’ must be ticked.</span>
+<span class="admin-task__permissions">Permissions required: User must be marked as staff; ‘Edit users’ details’ must be ticked.</span>
 
 <img alt="From the user admin page you can administer staff accounts" src="/assets/img/pro-user-guide/user-admin-page.png" class="admin-screenshot" />
 
@@ -478,29 +478,43 @@ You’ll see a table of existing users. Below this is the ‘add user’ interfa
 
 First create the basic user account by inputting a name and email address, plus any other contact
 details desired. Once this is done and you have saved the input, you can edit the account to assign
-any permissions required.
+any roles or permissions required.
 
 You can use the same form to create a user account for a resident or a member of staff, so tick
 ‘staff user’ if you wish to create an admin account.
 
 The new staff user can then log in via the normal method.
 
-#### Assigning permissions
+#### Creating roles
+
+<span class="admin-task__permissions">Permissions required: User must be marked as staff; ‘Edit other users' permissions must be ticked.</span>
+
+Go to the ‘Roles’ tab in the admin menu.
+
+Here you can create a group of permissions, called a ‘role’. See [Staff user
+accounts](../staff-user-accounts/) for some possible examples, but you can use
+whatever makes sense to your own organisation.
+
+Once you have created a role, you can then assign a user to one or more roles
+to give that user access to all the permissions of those roles, without having
+to assign permissions individually for each user.
+
+#### Assigning roles and permissions
 
 <span class="admin-task__permissions">Permissions required: User must be marked as staff; ‘Edit other users' permissions must be ticked.</span>
 
 <img alt="You can assign permissions to users on this screen" src="/assets/img/pro-user-guide/user-admin-permissions.png" class="admin-screenshot" />
 
 Once you have created the basic staff user account, you’ll be taken to a page where you can assign
-permissions.
+roles and permissions.
 
 You can also always edit any user from the table at the top of the Users page by clicking ‘edit’.
-Check the boxes relating to the permissions you wish that user to have, and click ‘submit changes’.
+Select the roles or permissions you wish that user to have, and click ‘submit changes’.
 
 
 #### Setting categories or areas
 
-<span class="admin-task__permissions">Permissions required: User must be marked as staff; ‘Edit other users' permissions’ must be ticked.</span>
+<span class="admin-task__permissions">Permissions required: User must be marked as staff; ‘Assign users to areas’ must be ticked (for areas).</span>
 
 <img alt="You can allocate categories to individual users by checking the relevant category boxes" src="/assets/img/pro-user-guide/user-admin-categories.png" class="admin-screenshot" />
 
diff --git a/docs/pro-manual/admin-tasks.md b/docs/pro-manual/admin-tasks.md
index 3dd6e30e1..933592d79 100644
--- a/docs/pro-manual/admin-tasks.md
+++ b/docs/pro-manual/admin-tasks.md
@@ -7,9 +7,14 @@ user-guide: true
 
 # Administrator tasks
 
-If you find that you cannot perform any of the tasks detailed below when logged into your FixMyStreet account, it is likely that your account has not been given the relevant permissions.
+If you find that you cannot perform any of the tasks detailed below when logged
+into your FixMyStreet account, it is likely that your account has not been
+given the relevant permissions or role.
 
-Contact your account administrator to request these permissions. Accompanying each task covered in this document, you will see ‘permissions required’, listing the checkboxes an Administrator must tick on your account for you to be able to perform this task.
+Contact your account administrator to request these permissions. Accompanying
+each task covered in this document, you will see ‘permissions required’,
+listing the permissions an Administrator must give you (either individually or
+via a role) for you to be able to perform this task.
 
 {% include admin-tasks-content.md %}
 
diff --git a/docs/pro-manual/index.md b/docs/pro-manual/index.md
index 85ed8377f..ee5af3990 100644
--- a/docs/pro-manual/index.md
+++ b/docs/pro-manual/index.md
@@ -48,7 +48,7 @@ been developed in consultation with UK councils.
 FixMyStreet Pro offers enhanced features to client councils, including:
 -  A FixMyStreet instance for the council website, providing the council's fault-reporting
 interface, and branded to look like the rest of the site
--  A variety of permissions which can be allocated to staff at a granular level
+-  A variety of permissions which can be allocated to staff at a granular level, and grouped into custom roles
 -  Simple channels of communication with report makers, through status updates and
 template responses
 -  The ability to moderate, edit or remove reports
@@ -58,4 +58,4 @@ Depending on which type of installation the council has opted for, there may als
 -  The ability to view and update reports even when offline
 -  Workflow prioritisation and shortlist generation
 -  The integration of council-owned assets, such as bins or streetlights, into the map
-interface
\ No newline at end of file
+interface
diff --git a/docs/pro-manual/staff-user-accounts.md b/docs/pro-manual/staff-user-accounts.md
index 3712dfcf5..1ea927fe9 100644
--- a/docs/pro-manual/staff-user-accounts.md
+++ b/docs/pro-manual/staff-user-accounts.md
@@ -46,13 +46,14 @@ the end of your session.
 You can change your password at any time by clicking on ‘Your account’ in the top menu bar.
 
 
-## Permissions
+## Permissions and Roles
 
-Staff accounts can be assigned a variety of permissions, depending on each team member’s needs
-or responsibilities. Permissions can be combined in any way.
+Staff accounts can be assigned a variety of permissions or roles, depending on
+each team member’s needs or responsibilities. Permissions can be combined in
+any way, grouped into custom roles, or applied individually.
 
 Some common staff roles and the appropriate permissions are shown in the table below, but you
-can tailor your permissions to best reflect your team’s operations.
+can tailor your permissions and roles to best reflect your team’s operations.
 
 
 <table class="table table--responsive">
diff --git a/docs/running/staff.md b/docs/running/staff.md
index 77ca05c8e..4330190e2 100644
--- a/docs/running/staff.md
+++ b/docs/running/staff.md
@@ -11,8 +11,8 @@ author: matthew
 Staff users are a middle rung of account, inbetween normal users of the site
 and superusers with full access to everything. They are associated with a
 particular body, and can have access to different features, depending upon the
-permissions granted to them. All their abilities only apply to reports made
-to the body with which they are associated; all staff users have access to all
-report states, not just open/fixed.
+permissions or roles granted to them. All their abilities only apply to reports
+made to the body with which they are associated; all staff users have access to
+all report states, not just open/fixed.
 
 {% include admin-tasks-content.md %}
diff --git a/docs/running/users.md b/docs/running/users.md
index 87b38f0d2..48cb2a791 100644
--- a/docs/running/users.md
+++ b/docs/running/users.md
@@ -117,12 +117,13 @@ FixMyStreet website).
 You can mark any FixMyStreet user as belonging to a body. This marks them as a
 "staff user" for that body. Staff users have extra privileges *which only apply
 to problem reports under the jurisdiction of the body to which the use
-belongs*. These permissions can be set on a per-user basis.
+belongs*. Permissions can be grouped into custom roles, and these roles and
+individual permissions can be set on a per-user basis.
 
 To set (or revoke) staff user status, choose **Users** in the admin, and enter
 the email or name. (It's also possible to access a user via the reports they
 have made). Choose the appropriate body from the **Body** dropdown. Normal
-(not staff) users have no body associated. Then you can assign permissions
+(not staff) users have no body associated. Then you can assign roles or permissions
 to that user, depending upon what they require access to.
 
 For full details of what staff accounts can do, please see the