Merge branch 'msj-health-issue-mvc-docs' into 'master'

Issue health MVC docs

See merge request gitlab-org/gitlab!26498

doc/user/group/epics/index.md

@@ -23,7 +23,7 @@ graph TD
     Parent_epic --> Issue1
     Parent_epic --> Child_epic
     Child_epic --> Issue2
-````
+```
 
 ## Use cases
 
@@ -184,6 +184,8 @@ have a [start or due date](#start-date-and-due-date), a
 
 ![Child epics roadmap](img/epic_view_roadmap_v12_9.png)
 
+---
+
 ## Reordering issues and child epics
 
 > [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/9367) in GitLab 12.5.
@@ -240,6 +242,8 @@ You can always reopen it using the reopen button.
 
 ![reopen epic - button](img/button_reopen_epic.png)
 
+---
+
 ### Using quick actions
 
 You can close or reopen an epic using [Quick actions](../../project/quick_actions.md)
@@ -251,9 +255,12 @@ link in the issue sidebar.
 
 ![containing epic](img/containing_epic.png)
 
+---
+
 ## Promoting an issue to an epic
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/3777) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.6.
+> - In [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/37081), it was moved to the Premium tier.
 
 If you have [permissions](../../permissions.md) to close an issue and create an
 epic in the parent group, you can promote an issue to an epic with the `/promote`
@@ -276,10 +283,11 @@ The following issue metadata will be copied to the epic:
 
 ## Searching for an epic from epics list page
 
-> Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.5.
+> - Introduced in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.5.
+> - In [GitLab 12.8](https://gitlab.com/gitlab-org/gitlab/issues/37081), it was moved to the Premium tier.
 
 You can search for an epic from the list of epics using filtered search bar (similar to
-that of Issues and Merge requests) based on following parameters:
+that of Issues and Merge Requests) based on following parameters:
 
 - Title or description
 - Author name / username
@@ -287,22 +295,26 @@ that of Issues and Merge requests) based on following parameters:
 
 ![epics search](img/epics_search.png)
 
-To search, go to the list of epics and click on the field **Search or filter results...**.
+To search, go to the list of epics and click on the field **Search or filter results**.
 It will display a dropdown menu, from which you can add an author. You can also enter plain
 text to search by epic title or description. When done, press <kbd>Enter</kbd> on your
 keyboard to filter the list.
 
 You can also sort epics list by:
 
-- **Created date**
-- **Last updated**
-- **Start date**
-- **Due date**
+- Created date
+- Last updated
+- Start date
+- Due date
 
-Each option contains a button that can toggle the order between **ascending** and **descending**. The sort option and order will be persisted to be used wherever epics are browsed including the [roadmap](../roadmap/index.md).
+Each option contains a button that can toggle the order between **Ascending** and **Descending**.
+The sort option and order is saved and used wherever you browse epics, including the
+[Roadmap](../roadmap/index.md).
 
 ![epics sort](img/epics_sort.png)
 
+---
+
 ## Permissions
 
 If you have access to view an epic and have access to view an issue already
@@ -315,7 +327,7 @@ Note that for a given group, the visibility of all projects must be the same as
 the group, or less restrictive. That means if you have access to a group's epic,
 then you already have access to its projects' issues.
 
-You may also consult the [group permissions table](../../permissions.md#group-members-permissions).
+You can also consult the [group permissions table](../../permissions.md#group-members-permissions).
 
 ## Thread
 
@@ -323,20 +335,20 @@ You may also consult the [group permissions table](../../permissions.md#group-me
   These text fields also fully support
   [GitLab Flavored Markdown](../../markdown.md#gitlab-flavored-markdown-gfm).
 
-## Comment, or start a thread
+## Comment or start a thread
 
-Once you wrote your comment, you can either:
+Once you write your comment, you can either:
 
-- Click "Comment" and your comment will be published.
-- Click "Start thread": start a thread within that epic's discussion to discuss specific points.
+- Click **Comment**, and your comment will be published.
+- Click **Start thread**, and you will start a thread within that epic's discussion.
 
 ## Award emoji
 
-- You can [award an emoji](../../award_emojis.md) to that epic or its comments.
+You can [award an emoji](../../award_emojis.md) to that epic or its comments.
 
 ## Notifications
 
-- [Receive notifications](../../profile/notifications.md) for epic events.
+You can [turn on notifications](../../profile/notifications.md) to be alerted about epic events.
 
 <!-- ## Troubleshooting
 

doc/user/project/issues/index.md

@@ -50,7 +50,8 @@ must be set.
             </ul>
             <li>State</li>
             <ul>
-                <li>Status (open/closed)</li>
+                <li>State (open or closed)</li>
+                <li>Status (On track, Needs attention, or At risk)</li>
                 <li>Confidentiality</li>
                 <li>Tasks (completed vs. outstanding)</li>
             </ul>
@@ -109,8 +110,7 @@ view, you can also make certain changes [in bulk](../bulk_editing.md) to the dis
 For more information, see the [Issue Data and Actions](issue_data_and_actions.md) page
 for a rundown of all the fields and information in an issue.
 
-You can sort a list of issues several ways, including by issue creation date, milestone due date,
-etc. For more information, see the [Sorting and Ordering Issue Lists](sorting_issue_lists.md) page.
+You can sort a list of issues in several ways, for example by issue creation date, milestone due date. For more information, see the [Sorting and Ordering Issue Lists](sorting_issue_lists.md) page.
 
 ### Issue boards
 
@@ -157,12 +157,38 @@ To prevent duplication of issues for the same topic, GitLab searches for similar
 when new issues are being created.
 
 When typing in the title in the **New Issue** page, GitLab searches titles and descriptions
-across all issues the user has access to in the current project. Up 5 similar issues,
+across all issues the user has access to in the current project. Up to five similar issues,
 sorted by most recently updated, are displayed below the title box. Note that this feature
 requires [GraphQL](../../../api/graphql/index.md) to be enabled.
 
 ![Similar issues](img/similar_issues.png)
 
+---
+
+### Status **(ULTIMATE)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/36427) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 12.9.
+
+To help you track the status of your issues, you can assign a status to each issue to flag work that's progressing as planned or needs attention to keep on schedule:
+
+- `On track` (green)
+- `Needs attention` (amber)
+- `At risk` (red)
+
+!["On track" health status on an issue](img/issue_health_status_v12_9.png)
+
+---
+
+#### Enable issue health status
+
+This feature comes with the `:save_issuable_health_status` feature flag disabled by default. However, in some cases
+this feature is incompatible with old configuration. To turn on the feature while configuration is
+migrated, ask a GitLab administrator with Rails console access to run the following command:
+
+```ruby
+Feature.enable(:save_issuable_health_status)
+```
+
 ## Other Issue actions
 
 - [Create an issue from a template](../../project/description_templates.md#using-the-templates)