Pared down for CTRT and reordered topics

doc/user/discussions/index.md

@@ -20,7 +20,7 @@ In a comment, you can enter [Markdown](../markdown.md) and use [quick actions](.
 You can [suggest code changes](../project/merge_requests/reviews/suggestions.md) in your commit diff comment,
 which the user can accept through the user interface.
 
-## Where you can create comments
+## Places you can add comments
 
 You can create comments in places like:
 
@@ -34,6 +34,141 @@ You can create comments in places like:
 
 Each object can have as many as 5,000 comments.
 
+## Add a comment to a merge request diff
+
+You can add comments to a merge request diff. These comments
+persist, even when you:
+
+- Force-push after a rebase.
+- Amend a commit.
+
+To add a commit diff comment:
+
+1. To select a specific commit, on the merge request, select the **Commits** tab, select the commit
+   message. To view the latest commit, select the **Changes** tab.
+1. By the line you want to comment on, hover over the line number and select **{comment}**.
+   You can select multiple lines by dragging the **{comment}** icon.
+1. Type your comment and select **Start a review** or **Add comment now**.
+
+The comment is displayed on the merge request's **Discussions** tab.
+
+The comment is not displayed on your project's **Repository > Commits** page.
+
+NOTE:
+When your comment contains a reference to a commit included in the merge request,
+it's automatically converted to a link in the context of the current merge request.
+For example, `28719b171a056960dfdc0012b625d0b47b123196` becomes
+`https://gitlab.example.com/example-group/example-project/-/merge_requests/12345/diffs?commit_id=28719b171a056960dfdc0012b625d0b47b123196`.
+
+## Add a comment to a commit
+
+You can add comments and threads to a particular commit.
+
+1. On the top bar, select **Menu > Projects** and find your project.
+1. On the left sidebar, select **Repository > Commits**.
+1. Below the commits, in the **Comment** field, enter a comment.
+1. Select **Comment** or select the down arrow (**{chevron-down}**) to select **Start thread**.
+
+WARNING:
+Threads created this way are lost if the commit ID changes after a
+force push.
+
+## Add a comment to an image
+
+In merge requests and commit detail views, you can add a comment to an image.
+This comment can also be a thread.
+
+1. Hover your mouse over the image.
+1. Select the location where you want to comment.
+
+An icon is displayed on the image and a comment field is displayed.
+
+![Start image thread](img/start_image_discussion.gif)
+
+## Reply to a comment by sending email
+
+If you have ["reply by email"](../../administration/reply_by_email.md) configured,
+you can reply to comments by sending an email.
+
+- When you reply to a standard comment, another standard comment is created.
+- When you reply to a threaded comment, it creates a reply in the thread.
+
+You can use [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md) in your email replies.
+
+## Who can edit comments
+
+You can edit your own comment at any time.
+
+Anyone with the [Maintainer role](../permissions.md) or
+higher can also edit a comment made by someone else.
+
+## Prevent comments by locking an issue
+
+You can prevent public comments in an issue or merge request.
+When you do, only project members can add and edit comments.
+
+Prerequisite:
+
+- In merge requests, you must have at least the Developer role.
+- In issues, you must have at least the Reporter role.
+
+1. On the right sidebar, next to **Lock issue** or **Lock merge request**, select **Edit**.
+1. On the confirmation dialog, select **Lock**.
+
+Notes are added to the page details.
+
+If an issue or merge request is locked and closed, you cannot reopen it.
+
+## Mark a comment as confidential
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207473) in GitLab 13.9.
+> - [Deployed behind a feature flag](../feature_flags.md), disabled by default.
+> - Disabled on GitLab.com.
+> - Not recommended for production use.
+> - To use in GitLab self-managed instances, ask a GitLab administrator to enable it. **(FREE SELF)**
+
+WARNING:
+This feature might not be available to you. Check the **version history** note above for details.
+
+You can make a comment confidential, so that it is visible only to project members
+who have at least the Reporter role.
+
+1. Below the comment, select the **Make this comment confidential** checkbox.
+1. Select **Comment**.
+
+![Confidential comments](img/confidential_comments_v13_9.png)
+
+## Show only comments
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26723) in GitLab 11.5.
+
+For issues and merge requests with many comments, you can filter the page to show comments only.
+
+1. Open a merge request's **Discussion** tab, or epic or issue's **Overview** tab.
+1. On the right side of the page, select from the filter:
+   - **Show all activity**: Display all user comments and system notes
+     (issue updates, mentions from other issues, changes to the description, and so on).
+   - **Show comments only**: Display only user comments.
+   - **Show history only**: Display only activity notes.
+
+![Notes filters dropdown options](img/index_notes_filters.png)
+
+GitLab saves your preference, so it persists when you visit the same page again
+from any device you're logged into.
+
+## Assign an issue to the commenting user
+
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191455) in GitLab 13.1.
+
+You can assign an issue to a user who made a comment.
+
+1. In the comment, select the **More Actions** menu.
+1. Select **Assign to commenting user**.
+
+![Assign to commenting user](img/quickly_assign_commenter_v13_1.png)
+
+Select the button again to unassign the commenter.
+
 ## Create a thread by replying to a standard comment
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/30299) in GitLab 11.9.
@@ -78,23 +213,6 @@ A threaded comment is created.
 
 ![Thread comment](img/discussion_comment.png)
 
-## Reply to a comment by sending email
-
-If you have ["reply by email"](../../administration/reply_by_email.md) configured,
-you can reply to comments by sending an email.
-
-- When you reply to a standard comment, another standard comment is created.
-- When you reply to a threaded comment, it creates a reply in the thread.
-
-You can use [Markdown](../markdown.md) and [quick actions](../project/quick_actions.md) in your email replies.
-
-## Who can edit comments
-
-You can edit your own comment at any time.
-
-Anyone with the [Maintainer role](../permissions.md) or
-higher can also edit a comment made by someone else.
-
 ## Resolve a thread
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/merge_requests/5022) in GitLab 8.11.
@@ -172,133 +290,6 @@ with a new push.
 Threads are now resolved if a push makes a diff section outdated.
 Threads on lines that don't change and top-level resolvable threads are not resolved.
 
-## Commit threads in the context of a merge request
-
-For reviewers with commit-based workflow, it may be useful to add threads to
-specific commit diffs in the context of a merge request. These threads
-persist through a commit ID change when:
-
-- force-pushing after a rebase
-- amending a commit
-
-To create a commit diff thread:
-
-1. Navigate to the merge request **Commits** tab. A list of commits that
-   constitute the merge request are shown.
-
-   ![Merge request commits tab](img/merge_request_commits_tab.png)
-
-1. Navigate to a specific commit, select the **Changes** tab (where you
-   are only be presented diffs from the selected commit), and leave a comment.
-
-   ![Commit diff discussion in merge request context](img/commit_comment_mr_context.png)
-
-1. Any threads created this way are shown in the merge request's
-   **Discussions** tab and are resolvable.
-
-   ![Merge request Discussions tab](img/commit_comment_mr_discussions_tab.png)
-
-Threads created this way only appear in the original merge request
-and not when navigating to that commit under your project's
-**Repository > Commits** page.
-
-NOTE:
-When a link of a commit reference is found in a thread inside a merge
-request, it is automatically converted to a link in the context of the
-current merge request.
-
-## Add a comment to a commit
-
-You can add comments and threads to a particular commit.
-
-1. On the top bar, select **Menu > Projects** and find your project.
-1. On the left sidebar, select **Repository > Commits**.
-1. Below the commits, in the **Comment** field, enter a comment.
-1. Select **Comment** or select the down arrow (**{chevron-down}**) to select **Start thread**.
-
-WARNING:
-Threads created this way are lost if the commit ID changes after a
-force push.
-
-## Add a comment to an image
-
-In merge requests and commit detail views, you can add a comment to an image.
-This comment can also be a thread.
-
-1. Hover your mouse over the image.
-1. Select the location where you want to comment.
-
-An icon is displayed on the image and a comment field is displayed.
-
-![Start image thread](img/start_image_discussion.gif)
-
-## Prevent comments by locking an issue
-
-You can prevent public comments in an issue or merge request.
-When you do, only project members can add and edit comments.
-
-Prerequisite:
-
-- In merge requests, you must have at least the Developer role.
-- In issues, you must have at least the Reporter role.
-
-1. On the right sidebar, next to **Lock issue** or **Lock merge request**, select **Edit**.
-1. On the confirmation dialog, select **Lock**.
-
-Notes are added to the page details.
-
-If an issue or merge request is locked and closed, you cannot reopen it.
-
-## Mark a comment as confidential
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/207473) in GitLab 13.9.
-> - [Deployed behind a feature flag](../feature_flags.md), disabled by default.
-> - Disabled on GitLab.com.
-> - Not recommended for production use.
-> - To use in GitLab self-managed instances, ask a GitLab administrator to enable it. **(FREE SELF)**
-
-WARNING:
-This feature might not be available to you. Check the **version history** note above for details.
-
-You can make a comment confidential, so that it is visible only to project members
-who have at least the Reporter role.
-
-1. Below the comment, select the **Make this comment confidential** checkbox.
-1. Select **Comment**.
-
-![Confidential comments](img/confidential_comments_v13_9.png)
-
-## Show only comments
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/26723) in GitLab 11.5.
-
-For issues and merge requests with many comments, you can filter the page to show comments only.
-
-1. Open a merge request's **Discussion** tab, or epic or issue's **Overview** tab.
-1. On the right side of the page, select from the filter:
-   - **Show all activity**: Display all user comments and system notes
-     (issue updates, mentions from other issues, changes to the description, and so on).
-   - **Show comments only**: Display only user comments.
-   - **Show history only**: Display only activity notes.
-
-![Notes filters dropdown options](img/index_notes_filters.png)
-
-GitLab saves your preference, so it persists when you visit the same page again
-from any device you're logged into.
-
-## Assign an issue to the commenting user
-
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/191455) in GitLab 13.1.
-
-You can assign an issue to a user who made a comment.
-
-1. In the comment, select the **More Actions** menu.
-1. Select **Assign to commenting user**.
-
-![Assign to commenting user](img/quickly_assign_commenter_v13_1.png)
-
-Select the button again to unassign the commenter.
-
 ## Enable or disable confidential comments **(FREE SELF)**
 
 Confidential comments are under development and not ready for production use. The feature is