Add documentation for discussion resolution.

6 files changed, 40 insertions, 8 deletions

diff --git a/doc/user/project/merge_requests/img/discussion_view.png b/doc/user/project/merge_requests/img/discussion_view.png
new file mode 100644
index 00000000000..83bb60acce2
--- /dev/null
+++ b/doc/user/project/merge_requests/img/discussion_view.png
diff --git a/doc/user/project/merge_requests/img/discussions_resolved.png b/doc/user/project/merge_requests/img/discussions_resolved.png
new file mode 100644
index 00000000000..85428129ac8
--- /dev/null
+++ b/doc/user/project/merge_requests/img/discussions_resolved.png
diff --git a/doc/user/project/merge_requests/img/resolve_comment_button.png b/doc/user/project/merge_requests/img/resolve_comment_button.png
new file mode 100644
index 00000000000..2c4ab2f5d53
--- /dev/null
+++ b/doc/user/project/merge_requests/img/resolve_comment_button.png
diff --git a/doc/user/project/merge_requests/img/resolve_discussion_button.png b/doc/user/project/merge_requests/img/resolve_discussion_button.png
new file mode 100644
index 00000000000..73f265bb101
--- /dev/null
+++ b/doc/user/project/merge_requests/img/resolve_discussion_button.png
diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/project/merge_requests/merge_request_discussion_resolution.md
new file mode 100644
index 00000000000..2559f5f5250
--- /dev/null
+++ b/doc/user/project/merge_requests/merge_request_discussion_resolution.md
@@ -0,0 +1,40 @@
+# Merge Request discussion resolution
+
+> [Introduced][ce-5022] in GitLab 8.11.
+
+Discussion resolution helps keep track of progress during code review.
+Resolving comments prevents you from forgetting to address feedback and lets you
+hide discussions that are no longer relevant.
+
+!["A discussion between two people on a piece of code"][discussion-view]
+
+Comments and discussions can be resolved by anyone with at least Developer
+access to the project, as well as by the author of the merge request.
+
+## Marking a comment or discussion as resolved
+
+You can mark a discussion as resolved by clicking the "Resolve discussion"
+button at the bottom of the discussion.
+
+!["Resolve discussion" button][resolve-discussion-button]
+
+Alternatively, you can mark each comment as resolved individually.
+
+!["Resolve comment" button][resolve-comment-button]
+
+## Jumping between unresolved discussions
+
+When a merge request has a large number of comments it can be difficult to track
+what remains unresolved. You can jump between unresolved discussions with the
+Jump button next to the Reply field on a discussion.
+
+You can also jump to the first unresolved discussion from the button next to the
+resolved discussions tracker.
+
+!["3/4 discussions resolved"][discussions-resolved]
+
+[ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022
+[resolve-discussion-button]: img/resolve_discussion_button.png
+[resolve-comment-button]: img/resolve_comment_button.png
+[discussion-view]: img/discussion_view.png
+[discussions-resolved]: img/discussions_resolved.png
diff --git a/doc/user/project/merge_requests/resolve_inline_comments.md b/doc/user/project/merge_requests/resolve_inline_comments.md
deleted file mode 100644
index 0189001d004..00000000000
--- a/doc/user/project/merge_requests/resolve_inline_comments.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# Resolve inline comments
-
->**Note:** [Introduced][ce-5022] in GitLab 8.11.
-
-## Overview
-
-
-[ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022