Locked issues / mrs docs

2 files changed, 16 insertions, 24 deletions

diff --git a/doc/user/discussions/index.md b/doc/user/discussions/index.md
index ab46befb91c..23506261f12 100644
--- a/doc/user/discussions/index.md
+++ b/doc/user/discussions/index.md
@@ -153,42 +153,34 @@ comments in greater detail.
 
 ![Discussion comment](img/discussion_comment.png)
 
-## Locking discussions
+## Lock discussions
 
 > [Introduced][ce-14531] in GitLab 10.1.
 
-There might be some cases where a discussion is better off if it's locked down.
-For example:
+For large projects with many contributors, it may be useful to stop discussions
+in issues or merge requests in these scenarios:
 
-- Discussions that are several years old and the issue/merge request is closed,
-  but people continue to try to resurrect the discussion.
-- Discussions where someone or a group of people are trolling, are abusive, or
-  in-general are causing the discussion to be unproductive.
+- The project maintainer has already resolved the discussion and it is not helpful
+for continued feedback. The project maintainer has already directed new conversation
+to newer issues or merge requests.
+- The people participating in the discussion are trolling, abusive, or otherwise 
+being unproductive. 
 
-In locked discussions, only team members can write new comments and edit the old
-ones.
+In these cases, a user with Master permissions or higher in the project can lock (and unlock)
+an issue or a merge request, using the "Lock" section in the sidebar:
 
-To lock or unlock a discussion, you need to have at least Master [permissions]:
-
-1. Find the "Lock" section in the sidebar and click **Edit**
-1. In the dialog that will appear, you can choose to turn on or turn off the
-   discussion lock
-1. Optionally, leave a comment to explain your reasoning behind that action
-
-| Turn off discussion lock | Turn on discussion lock |
+| Unlock | Lock |
 | :-----------: | :----------: |
 | ![Turn off discussion lock](img/turn_off_lock.png) | ![Turn on discussion lock](img/turn_on_lock.png) |
 
-Every change is indicated by a system note in the issue's or merge request's
-comments.
+System notes indicate locking and unlocking.
 
 ![Discussion lock system notes](img/discussion_lock_system_notes.png)
 
-Once an issue or merge request is locked, project members can see the indicator
-in the comment area, whereas non project members can only see the information
-that the discussion is locked.
+In a locked issue or merge request, only team members can add new comments and 
+edit existing comments. Non-team members are restricted from adding or editing comments.
 
-| Team member | Not a member |
+| Team member | Non-team member |
 | :-----------: | :----------: |
 | ![Comment form member](img/lock_form_member.png) | ![Comment form non-member](img/lock_form_non_member.png) |
 
diff --git a/doc/user/permissions.md b/doc/user/permissions.md
index be72d42625a..9b096d26081 100644
--- a/doc/user/permissions.md
+++ b/doc/user/permissions.md
@@ -25,7 +25,7 @@ The following table depicts the various user permission levels in a project.
 | Create confidential issue             | ✓ [^1]  | ✓          | ✓           | ✓        | ✓      |
 | View confidential issues              | (✓) [^2] | ✓          | ✓           | ✓        | ✓      |
 | Leave comments                        | ✓ [^1]  | ✓          | ✓           | ✓        | ✓      |
-| Lock comments                         |         |            |             | ✓        | ✓      |
+| Lock discussions (issues and merge requests) |  |            |             | ✓        | ✓      |
 | See a list of jobs                    | ✓ [^3]  | ✓          | ✓           | ✓        | ✓      |
 | See a job   log                       | ✓ [^3]  | ✓          | ✓           | ✓        | ✓      |
 | Download and browse job artifacts     | ✓ [^3]  | ✓          | ✓           | ✓        | ✓      |