Started on resolvable discussions docs

15 files changed, 59 insertions, 31 deletions

diff --git a/doc/README.md b/doc/README.md
index 9e6a5b4ed44..67deda1eaeb 100644
--- a/doc/README.md
+++ b/doc/README.md
@@ -23,6 +23,7 @@ All technical content published by GitLab lives in the documentation, including:
 - [Importing and exporting projects between instances](user/project/settings/import_export.md).
 - [Importing to GitLab](workflow/importing/README.md) Import your projects from GitHub, Bitbucket, GitLab.com, FogBugz and SVN into GitLab.
 - [Markdown](user/markdown.md) GitLab's advanced formatting system.
+- [Discussions](user/discussions.md) Get the most out of your conversations.
 - [Migrating from SVN](workflow/importing/migrating_from_svn.md) Convert a SVN repository to Git and GitLab.
 - [Permissions](user/permissions.md) Learn what each role in a project (external/guest/reporter/developer/master/owner) can do.
 - [Profile Settings](profile/README.md)
diff --git a/doc/user/project/merge_requests/merge_request_discussion_resolution.md b/doc/user/discussions.md
index 230e957f045..23a4dee94c6 100644
--- a/doc/user/project/merge_requests/merge_request_discussion_resolution.md
+++ b/doc/user/discussions.md
@@ -1,17 +1,25 @@
-# Merge Request discussion resolution
+# Discussions
 
-> [Introduced][ce-5022] in GitLab 8.11.
+The ability to contribute conversationally is offered throughout GitLab.
+
+## Standard Comments
+
+Standard comments can be added to issues, merge requests, snippets, commits and commit diffs.
+
+## Resolvable Discussions
 
-Discussion resolution helps keep track of progress during code review.
+Resolvable discussions can be added to merge request diffs, merge requests, issues, commits and snippets.
+
+Discussion resolution helps keep track of progress during planning or 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.
+access to the project or the author of the merge request.
 
-## Marking a comment or discussion as resolved
+### 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.
@@ -22,7 +30,42 @@ Alternatively, you can mark each comment as resolved individually.
 
 !["Resolve comment" button][resolve-comment-button]
 
-## Jumping between unresolved discussions
+### Moving a single discussion to a new issue
+
+> [Introduced][ce-8266] in GitLab 9.1
+
+To create a new issue for a single discussion, you can use the **Resolve this
+discussion in a new issue** button.
+
+![Create issue for discussion](img/new_issue_for_discussion.png)
+
+This will direct you to a new issue prefilled with the content of the
+discussion, similar to the issues created for delegating multiple
+discussions at once.
+
+![New issue for a single discussion](img/preview_issue_for_discussion.png)
+
+Saving the issue will mark the discussion as resolved and add a note
+to the discussion referencing the new issue.
+
+[ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022
+[ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125
+[ce-7180]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7180
+[ce-8266]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8266
+[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
+
+## Merge request diffs
+
+> [Introduced][ce-5022] in GitLab 8.11.
+
+Discussions can be started on merge request diffs to keep track of progress during code review.
+
+!["A discussion between two people on a piece of code"][discussion-view]
+
+### 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
@@ -33,7 +76,7 @@ resolved discussions tracker.
 
 !["3/4 discussions resolved"][discussions-resolved]
 
-## Only allow merge requests to be merged if all discussions are resolved
+### Only allow merge requests to be merged if all discussions are resolved
 
 > [Introduced][ce-7125] in GitLab 8.14.
 
@@ -51,9 +94,9 @@ are resolved.
 
 ![Only allow merge if all the discussions are resolved message](img/only_allow_merge_if_all_discussions_are_resolved_msg.png)
 
-## Move all unresolved discussions in a merge request to an issue
+### Move all unresolved discussions in a merge request to an issue
 
-> [Introduced][ce-8266]
+> [Introduced][ce-8266] in GitLab 9.1
 
 To continue all open discussions in a merge request, click the button **Resolve
 all discussions in new issue**
@@ -78,29 +121,13 @@ add a note referring to the newly created issue.
 
 You can now proceed to merge the merge request from the UI.
 
-## Moving a single discussion to a new issue
 
-> [Introduced][ce-8266]
+## Issues, commits, snippets and merge requests
 
-To create a new issue for a single discussion, you can use the **Resolve this
-discussion in a new issue** button.
+> [Introduced][ce-7527] in GitLab 9.1.
 
-![Create issue for discussion](img/new_issue_for_discussion.png)
+Discussions can be started on issues, commits, snippets and merge requests.
 
-This will direct you to a new issue prefilled with the content of the
-discussion, similar to the issues created for delegating multiple
-discussions at once.
+Resolvable discussions can be added to merge request diffs, but they can also be added without a diff.
 
-![New issue for a single discussion](img/preview_issue_for_discussion.png)
-
-Saving the issue will mark the discussion as resolved and add a note
-to the discussion referencing the new issue.
-
-[ce-5022]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5022
-[ce-7125]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7125
-[ce-7180]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/7180
-[ce-8266]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8266
-[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
+To start a resolvable discussion, you can click on the `Comment` button dropdown and select `Start discussion`.
diff --git a/doc/user/project/merge_requests/img/btn_new_issue_for_all_discussions.png b/doc/user/img/btn_new_issue_for_all_discussions.png
index b15447ec290..b15447ec290 100644
--- a/doc/user/project/merge_requests/img/btn_new_issue_for_all_discussions.png
+++ b/doc/user/img/btn_new_issue_for_all_discussions.png
diff --git a/doc/user/project/merge_requests/img/discussion_view.png b/doc/user/img/discussion_view.png
index 2ee1db2eab3..2ee1db2eab3 100644
--- a/doc/user/project/merge_requests/img/discussion_view.png
+++ b/doc/user/img/discussion_view.png
diff --git a/doc/user/project/merge_requests/img/discussions_resolved.png b/doc/user/img/discussions_resolved.png
index 3fd496f6da5..3fd496f6da5 100644
--- a/doc/user/project/merge_requests/img/discussions_resolved.png
+++ b/doc/user/img/discussions_resolved.png
diff --git a/doc/user/project/merge_requests/img/new_issue_for_discussion.png b/doc/user/img/new_issue_for_discussion.png
index 93c9dad8921..93c9dad8921 100644
--- a/doc/user/project/merge_requests/img/new_issue_for_discussion.png
+++ b/doc/user/img/new_issue_for_discussion.png
diff --git a/doc/user/project/merge_requests/img/only_allow_merge_if_all_discussions_are_resolved.png b/doc/user/img/only_allow_merge_if_all_discussions_are_resolved.png
index 928c7d33898..928c7d33898 100644
--- a/doc/user/project/merge_requests/img/only_allow_merge_if_all_discussions_are_resolved.png
+++ b/doc/user/img/only_allow_merge_if_all_discussions_are_resolved.png
diff --git a/doc/user/project/merge_requests/img/only_allow_merge_if_all_discussions_are_resolved_msg.png b/doc/user/img/only_allow_merge_if_all_discussions_are_resolved_msg.png
index bcdc0250d7c..bcdc0250d7c 100644
--- a/doc/user/project/merge_requests/img/only_allow_merge_if_all_discussions_are_resolved_msg.png
+++ b/doc/user/img/only_allow_merge_if_all_discussions_are_resolved_msg.png
diff --git a/doc/user/project/merge_requests/img/preview_issue_for_discussion.png b/doc/user/img/preview_issue_for_discussion.png
index 2ee0653b2ba..2ee0653b2ba 100644
--- a/doc/user/project/merge_requests/img/preview_issue_for_discussion.png
+++ b/doc/user/img/preview_issue_for_discussion.png
diff --git a/doc/user/project/merge_requests/img/preview_issue_for_discussions.png b/doc/user/img/preview_issue_for_discussions.png
index 3fe0a666678..3fe0a666678 100644
--- a/doc/user/project/merge_requests/img/preview_issue_for_discussions.png
+++ b/doc/user/img/preview_issue_for_discussions.png
diff --git a/doc/user/project/merge_requests/img/resolve_comment_button.png b/doc/user/img/resolve_comment_button.png
index 70340108874..70340108874 100644
--- a/doc/user/project/merge_requests/img/resolve_comment_button.png
+++ b/doc/user/img/resolve_comment_button.png
diff --git a/doc/user/project/merge_requests/img/resolve_discussion_button.png b/doc/user/img/resolve_discussion_button.png
index ab454f661e0..ab454f661e0 100644
--- a/doc/user/project/merge_requests/img/resolve_discussion_button.png
+++ b/doc/user/img/resolve_discussion_button.png
diff --git a/doc/user/project/merge_requests/img/resolve_discussion_issue_notice.png b/doc/user/img/resolve_discussion_issue_notice.png
index e0ee6a39ffd..e0ee6a39ffd 100644
--- a/doc/user/project/merge_requests/img/resolve_discussion_issue_notice.png
+++ b/doc/user/img/resolve_discussion_issue_notice.png
diff --git a/doc/user/project/merge_requests/img/resolve_discussion_open_issue.png b/doc/user/img/resolve_discussion_open_issue.png
index 98d63278326..98d63278326 100644
--- a/doc/user/project/merge_requests/img/resolve_discussion_open_issue.png
+++ b/doc/user/img/resolve_discussion_open_issue.png
diff --git a/doc/user/project/merge_requests/index.md b/doc/user/project/merge_requests/index.md
index c759b7aaa4a..237d7db30fc 100644
--- a/doc/user/project/merge_requests/index.md
+++ b/doc/user/project/merge_requests/index.md
@@ -34,7 +34,7 @@ Keep track of the progress during a code review with resolving comments.
 Resolving comments prevents you from forgetting to address feedback and lets
 you hide discussions that are no longer relevant.
 
-[Read more about resolving discussion comments in merge requests reviews.](merge_request_discussion_resolution.md)
+[Read more about resolving discussion comments in merge requests reviews.](../../discussions.md)
 
 ## Resolve conflicts