Better information on blocking users

3 files changed, 115 insertions, 41 deletions

diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md
index 41ee7e62b2c..e6c86cc8f2e 100644
--- a/doc/user/abuse_reports.md
+++ b/doc/user/abuse_reports.md
@@ -1,6 +1,12 @@
 # Abuse reports
 
-Report abuse from users to GitLab administrators.
+You can report abuse from other GitLab users to GitLab administrators.
+
+A GitLab administrator [can then choose](admin_area/abuse_reports.md) to:
+
+- Remove the user, which deletes them from the instance.
+- Block the user, which denies them access to the instance.
+- Or remove the report, which retains the users access to the instance.
 
 You can report a user through their:
 
@@ -12,7 +18,8 @@ You can report a user through their:
 
 To report abuse from a user's profile page:
 
-1. Click on the exclamation point report abuse button at the top right of the user's profile.
+1. Click on the exclamation point report abuse button at the top right of the
+   user's profile.
 1. Complete an abuse report.
 1. Click the **Send report** button.
 
@@ -26,15 +33,18 @@ To report abuse from a user's comment:
 1. Click the **Send report** button.
 
 NOTE: **Note:**
-A URL to the reported user's comment will be
-pre-filled in the abuse report's **Message** field.
+A URL to the reported user's comment will be pre-filled in the abuse report's
+**Message** field.
 
 ## Reporting abuse through a user's issue or merge request
 
 The **Report abuse** button is displayed at the top right of the issue or merge request:
 
-- When **Report abuse** is selected from the menu that appears when the **Close issue** or **Close merge request** button is clicked, for users that have permission to close the issue or merge request.
-- When viewing the issue or merge request, for users that don't have permission to close the issue or merge request.
+- When **Report abuse** is selected from the menu that appears when the
+  **Close issue** or **Close merge request** button is clicked, for users that
+  have permission to close the issue or merge request.
+- When viewing the issue or merge request, for users that don't have permission
+  to close the issue or merge request.
 
 With the **Report abuse** button displayed, to submit an abuse report:
 
diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md
index 01c2d9607f5..8088c33fc9c 100644
--- a/doc/user/admin_area/abuse_reports.md
+++ b/doc/user/admin_area/abuse_reports.md
@@ -2,30 +2,60 @@
 
 View and resolve abuse reports from GitLab users.
 
-Admins can view abuse reports in the admin area and are able to
-resolve the reports by removing the reported user, blocking the reported user, or removing the report.
+GitLab administrators can view and [resolve](#resolving-abuse-reports) abuse
+reports in the Admin Area.
 
 ## Reporting abuse
 
-To find out more about reporting abuse, see [abuse reports user documentation](../abuse_reports.md).
+To find out more about reporting abuse, see [abuse reports user
+documentation](../abuse_reports.md).
 
 ## Resolving abuse reports
 
-To access abuse reports, go to **Admin area > Abuse Reports**.
+To access abuse reports, go to **Admin Area > Abuse Reports**.
 
 There are 3 ways to resolve an abuse report, with a button for each method:
 
-- Remove user & report: [Deletes the reported user](../profile/account/delete_account.md) from the instance and removes the abuse report from the list.
-- Block user: Blocks the reported user from the instance and does not remove the abuse report from the list.
-- Remove report: Removes the abuse report from the list and does not restrict the access for the reported user.
+- Remove user & report. This will:
+  - [Delete the reported user](../profile/account/delete_account.md) from the
+    instance.
+  - Remove the abuse report from the list.
+- [Block user](#blocking-users).
+- Remove report. This will:
+  - Remove the abuse report from the list.
+  - Remove access restrictions for the reported user.
+
+The following is an example of the **Abuse Reports** page:
 
 ![abuse-reports-page-image](img/abuse_reports_page.png)
 
-## Blocked users
+### Blocking users
+
+A blocked user cannot log in or access any repositories, but all of their data
+remains.
+
+Blocking a user:
+
+- Leaves them in the abuse report list.
+- Changes the **Block user** button to a disabled **Already blocked** button.
 
-Blocking a user will not remove the abuse report from the list.
+The user will be notified with the
+[following message](https://gitlab.com/gitlab-org/gitlab-ee/blob/master/app/workers/email_receiver_worker.rb#L38):
 
-Instead, the block button will be disabled and explain that the user is "Already blocked".
-You are still able to remove the user and/or report if necessary.
+```text
+Your account has been blocked. If you believe this is in error, contact a staff member.
+```
+
+After blocking, you can still either:
+
+- Remove the user and report if necessary.
+- Remove the report.
+
+The following is an example of a blocked user listed on the **Abuse Reports**
+page:
 
 ![abuse-report-blocked-user-image](img/abuse_report_blocked_user.png)
+
+NOTE: **Note:**
+Users can be [blocked](../../api/users.md#block-user) and
+[unblocked](../../api/users.md#unblock-user) using the GitLab API.
diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md
index 304a7984191..cbee79de493 100644
--- a/doc/user/profile/account/delete_account.md
+++ b/doc/user/profile/account/delete_account.md
@@ -1,37 +1,71 @@
-# Deleting a User Account
+# Deleting a User account
+
+Users can be deleted from a GitLab instance, either by:
+
+- The user themselves.
+- An administrator.
 
 NOTE: **Note:**
 Deleting a user will delete all projects in that user namespace.
 
-- As a user, you can delete your own account by navigating to **Settings** > **Account** and selecting **Delete account**
-- As an admin, you can delete a user account by navigating to the **Admin Area**, selecting the **Users** tab, selecting a user, and clicking on **Delete user**
+## As a user
+
+As a user, you can delete your own account by:
+
+1. Clicking on your avatar.
+1. Navigating to **Settings > Account**.
+1. Selecting **Delete account**.
+
+## As an administrator
+
+As an administrator, you can delete a user account by:
+
+1. Navigating to **Admin Area > Overview > Users**.
+1. Selecting a user.
+1. Under the **Account** tab, clicking:
+   - **Delete user** to delete only the user but maintaining their
+     [associated records](#associated-records).
+   - **Delete user and contributions** to delete the user and
+     their associated records.
+
+### Blocking a user
+
+In addition to blocking a user
+[via an abuse report](../../admin_area/abuse_reports.md#blocking-users),
+a user can be blocked directly from the Admin area. To do this:
+
+1. Navigate to  **Admin Area > Overview > Users**.
+1. Selecting a user.
+1. Under the **Account** tab, click **Block user**.
 
 ## Associated Records
 
-> Introduced for issues in [GitLab 9.0][ce-7393], and for merge requests, award
-  emoji, notes, and abuse reports in [GitLab 9.1][ce-10467].
-  Hard deletion from abuse reports and spam logs was introduced in
-  [GitLab 9.1][ce-10273], and from the API in [GitLab 9.3][ce-11853].
+> - Introduced for issues in
+>   [GitLab 9.0](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7393).
+> - Introduced for merge requests, award emoji, notes, and abuse reports in
+>   [GitLab 9.1](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10467).
+> - Hard deletion from abuse reports and spam logs was introduced in
+>   [GitLab 9.1](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10273),
+>   and from the API in
+>   [GitLab 9.3](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11853).
 
 When a user account is deleted, not all associated records are deleted with it.
 Here's a list of things that will **not** be deleted:
 
-- Issues that the user created
-- Merge requests that the user created
-- Notes that the user created
-- Abuse reports that the user reported
-- Award emoji that the user created
+- Issues that the user created.
+- Merge requests that the user created.
+- Notes that the user created.
+- Abuse reports that the user reported.
+- Award emoji that the user created.
 
 Instead of being deleted, these records will be moved to a system-wide
-user with the username "Ghost User", whose sole purpose is to act as a container for such records. Any commits made by a deleted user will still display the username of the original user.
-
-When a user is deleted from an [abuse report](../../admin_area/abuse_reports.md) or spam log, these associated
-records are not ghosted and will be removed, along with any groups the user
-is a sole owner of. Administrators can also request this behaviour when
-deleting users from the [API](../../../api/users.md#user-deletion) or the
-admin area.
-
-[ce-7393]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7393
-[ce-10273]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10273
-[ce-10467]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/10467
-[ce-11853]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/11853
+user with the username "Ghost User", whose sole purpose is to act as a container
+for such records. Any commits made by a deleted user will still display the
+username of the original user.
+
+When a user is deleted from an [abuse report](../../admin_area/abuse_reports.md)
+or spam log, these associated records are not ghosted and will be removed, along
+with any groups the user is a sole owner of.
+
+Administrators can also request this behavior when deleting users from the
+[API](../../../api/users.md#user-deletion) or the Admin Area.