Document the "Abuse reports" feature45552-abuse-reports-functionality-is-undocumented

Add documentation for both admins (/user/admin_area/abuse_reports.md)
and non-admins (/user/abuse_reports.md) to help them use
the abuse reports feature

13 files changed, 105 insertions, 2 deletions

diff --git a/doc/administration/index.md b/doc/administration/index.md
index 6083806af6c..89132cd95f0 100644
--- a/doc/administration/index.md
+++ b/doc/administration/index.md
@@ -95,6 +95,7 @@ created in snippets, wikis, and repos.
   - [Postfix for incoming email](reply_by_email_postfix_setup.md): Set up a
   basic Postfix mail server with IMAP authentication on Ubuntu for incoming
   emails.
+- [Abuse reports](../user/admin_area/abuse_reports.md): View and resolve abuse reports from your users.
 
 [reply by email]: reply_by_email.md
 [issues by email]: ../user/project/issues/create_new_issue.md#new-issue-via-email
diff --git a/doc/user/abuse_reports.md b/doc/user/abuse_reports.md
new file mode 100644
index 00000000000..78ab5fb12c3
--- /dev/null
+++ b/doc/user/abuse_reports.md
@@ -0,0 +1,69 @@
+# Abuse reports
+
+Report abuse from other GitLab users to instance administrators.
+
+You can report a user through their:
+
+- [Profile](#reporting-abuse-through-a-users-profile)
+- [Comments](#reporting-abuse-through-a-users-comment)
+- [Issues and Merge requests](#reporting-abuse-through-a-users-issue-or-merge-request)
+
+## Reporting abuse through a user's profile
+
+To report abuse from a user's profile page, click on the exclamation point
+report abuse button at the top right of the user's profile.
+
+![abuse-report-user-profile-image](img/abuse_report_user_profile.png)
+
+When the user has been reported, the report button turns red.
+
+![abuse-report-reported-user-profile-image](img/abuse_report_reported_user_profile.png)
+
+## Reporting abuse through a user's comment
+
+To report abuse from a user's comment:
+
+1. Click on the vertical ellipsis (⋮) more actions button to open the dropdown.
+1. Select **Report as abuse**.
+
+![abuse-report-user-comment-image](img/abuse_report_user_comment.png)
+
+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 process for reporting abuse from an issue or merge request depends on your permissions.
+
+If you have permission to close the issue or merge request:
+
+1. Select **Report abuse** in the dropdown to the right of the **Close issue** or **Close merge request** button.
+1. Click the resulting **Report abuse** button to visit the report creation page.
+
+![abuse-report-user-issue-or-merge-request-dropdown-image](img/abuse_report_user_issue_or_merge_request_dropdown.png)
+
+If you don't have permission, you click on the
+**Report abuse** button at the top right of the issue or merge request.
+
+![abuse-report-user-issue-or-merge-request-image](img/abuse_report_user_issue_or_merge_request.png)
+
+A URL to the reported user's issue or merge request will be pre-filled
+in the abuse report creation page.
+
+## Submitting an abuse report
+
+After reporting a user using any of the methods described above, you will be
+redirected to the report creation page.
+
+The user to be reported will be pre-filled and the message field should be used
+to explain the reason for the report.
+
+If you have reported the user through a comment, issue, or merge request,
+a URL to the comment, issue, or merge request is pre-filled in the message field.
+
+![abuse-report-creation-image](img/abuse_report_creation.png)
+
+## Managing abuse reports
+
+Admins are able to view and resolve abuse reports.
+For more information, see [abuse reports administration documentation](admin_area/abuse_reports.md).
diff --git a/doc/user/admin_area/abuse_reports.md b/doc/user/admin_area/abuse_reports.md
new file mode 100644
index 00000000000..4cdf99d5474
--- /dev/null
+++ b/doc/user/admin_area/abuse_reports.md
@@ -0,0 +1,32 @@
+# Abuse reports
+
+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.
+
+## Reporting abuse
+
+To find out more about reporting abuse, see [abuse reports user documentation](../abuse_reports.md).
+
+## Resolving abuse reports
+
+When you are signed in as a user with admin access, abuse reports can be viewed
+on the `/admin/abuse_reports` page.
+
+There are 3 ways to resolve an abuse report:
+
+- 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.
+
+![abuse-reports-page-image](img/abuse_reports_page.png)
+
+## Blocked users
+
+Blocking a user will not remove the abuse report from the list.
+
+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.
+
+![abuse-report-blocked-user-image](img/abuse_report_blocked_user.png)
diff --git a/doc/user/admin_area/img/abuse_report_blocked_user.png b/doc/user/admin_area/img/abuse_report_blocked_user.png
new file mode 100644
index 00000000000..0cb4c7bb8ac
--- /dev/null
+++ b/doc/user/admin_area/img/abuse_report_blocked_user.png
diff --git a/doc/user/admin_area/img/abuse_reports_page.png b/doc/user/admin_area/img/abuse_reports_page.png
new file mode 100644
index 00000000000..81dbe976cda
--- /dev/null
+++ b/doc/user/admin_area/img/abuse_reports_page.png
diff --git a/doc/user/img/abuse_report_creation.png b/doc/user/img/abuse_report_creation.png
new file mode 100644
index 00000000000..1fcdbc3b3ab
--- /dev/null
+++ b/doc/user/img/abuse_report_creation.png
diff --git a/doc/user/img/abuse_report_reported_user_profile.png b/doc/user/img/abuse_report_reported_user_profile.png
new file mode 100644
index 00000000000..5441c13605d
--- /dev/null
+++ b/doc/user/img/abuse_report_reported_user_profile.png
diff --git a/doc/user/img/abuse_report_user_comment.png b/doc/user/img/abuse_report_user_comment.png
new file mode 100644
index 00000000000..2afa5fa8db9
--- /dev/null
+++ b/doc/user/img/abuse_report_user_comment.png
diff --git a/doc/user/img/abuse_report_user_issue_or_merge_request.png b/doc/user/img/abuse_report_user_issue_or_merge_request.png
new file mode 100644
index 00000000000..f118a0bc98a
--- /dev/null
+++ b/doc/user/img/abuse_report_user_issue_or_merge_request.png
diff --git a/doc/user/img/abuse_report_user_issue_or_merge_request_dropdown.png b/doc/user/img/abuse_report_user_issue_or_merge_request_dropdown.png
new file mode 100644
index 00000000000..0e0aece2983
--- /dev/null
+++ b/doc/user/img/abuse_report_user_issue_or_merge_request_dropdown.png
diff --git a/doc/user/img/abuse_report_user_profile.png b/doc/user/img/abuse_report_user_profile.png
new file mode 100644
index 00000000000..42526a91318
--- /dev/null
+++ b/doc/user/img/abuse_report_user_profile.png
diff --git a/doc/user/index.md b/doc/user/index.md
index 08995032cb1..f1b579b849c 100644
--- a/doc/user/index.md
+++ b/doc/user/index.md
@@ -113,6 +113,7 @@ methods available in GitLab.
 user type (guest, reporter, developer, maintainer, owner).
 - [Feature highlight](feature_highlight.md): Learn more about the little blue dots
 around the app that explain certain features
+- [Abuse reports](abuse_reports.md): Report abuse from other GitLab users to instance administrators
 
 ## Groups
 
diff --git a/doc/user/profile/account/delete_account.md b/doc/user/profile/account/delete_account.md
index 49f0ce2cd79..1daa12a26ea 100644
--- a/doc/user/profile/account/delete_account.md
+++ b/doc/user/profile/account/delete_account.md
@@ -25,7 +25,7 @@ Here's a list of things that will not be deleted:
 Instead of being deleted, these records will be moved to a system-wide
 "Ghost User", whose sole purpose is to act as a container for such records.
 
-When a user is deleted from an abuse report or spam log, these associated
+When a user is deleted from an [abuse report][abuse-reports] 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
@@ -35,4 +35,4 @@ admin area.
 [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
-
+[abuse-reports]: ../../admin_area/abuse_reports.md