Merge branch 'docs-50503-issueboards-overview' into 'master'

Docs: improve Issue Boards overview (to deprecate feature page)

Closes #50503

See merge request gitlab-org/gitlab-ce!21905

5 files changed, 176 insertions, 113 deletions

diff --git a/doc/user/project/img/issue_board_milestone_lists.png b/doc/user/project/img/issue_board_milestone_lists.png
new file mode 100644
index 00000000000..91926f58f87
--- /dev/null
+++ b/doc/user/project/img/issue_board_milestone_lists.png
diff --git a/doc/user/project/img/issue_board_summed_weights.png b/doc/user/project/img/issue_board_summed_weights.png
new file mode 100644
index 00000000000..2288d767d8c
--- /dev/null
+++ b/doc/user/project/img/issue_board_summed_weights.png
diff --git a/doc/user/project/img/issue_boards_core.png b/doc/user/project/img/issue_boards_core.png
new file mode 100755
index 00000000000..9e819160861
--- /dev/null
+++ b/doc/user/project/img/issue_boards_core.png
diff --git a/doc/user/project/img/issue_boards_premium.png b/doc/user/project/img/issue_boards_premium.png
new file mode 100755
index 00000000000..bd9164b2961
--- /dev/null
+++ b/doc/user/project/img/issue_boards_premium.png
diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md
index 7c6d547d626..464fa5987c1 100644
--- a/doc/user/project/issue_board.md
+++ b/doc/user/project/issue_board.md
@@ -2,13 +2,44 @@
 
 > [Introduced][ce-5554] in [GitLab 8.11](https://about.gitlab.com/2016/08/22/gitlab-8-11-released/#issue-board).
 
+## Overview
+
 The GitLab Issue Board is a software project management tool used to plan,
 organize, and visualize a workflow for a feature or product release.
 It can be used as a [Kanban] or a [Scrum] board.
 
-![GitLab Issue Board](img/issue_board.png)
+It provides perfect pairing between issue tracking and project management,
+keeping everything in the same place, so that you don't need to jump
+between different platforms to organize your workflow.
 
-## Overview
+With GitLab Issue Boards, you organize your issues in lists that correspond to
+their assigned labels, visualizing issues designed as cards throughout that lists.
+
+You define your process and GitLab organizes it for you. You add your labels
+then create the corresponding list to pull in your existing issues. When
+you're ready, you can drag and drop your issue cards from one step to the next.
+
+![GitLab Issue Board - Core](img/issue_boards_core.png)
+
+**<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+Watch a [video presentation](https://youtu.be/UWsJ8tkHAa8) of
+Issue Boards** (version introduced in GitLab 8.11 - August 2016).
+
+### Advanced features of Issue Boards
+
+With [GitLab Starter](https://about.gitlab.com/pricing/), you can create
+[multiple issue boards](#multiple-issue-boards) for a given project. **[STARTER]**
+
+With [GitLab Premium](https://about.gitlab.com/pricing/), you can also create multiple
+issue boards for your groups, and add lists for [assignees](#assignee-lists) and
+[milestones](#milestone-lists). **[PREMIUM]**
+
+Check all the [advanced features of Issue Boards](#gitlab-enterprise-features-for-issue-boards)
+below.
+
+![GitLab Issue Boards - Premium](img/issue_boards_premium.png)
+
+## How it works
 
 The Issue Board builds on GitLab's existing
 [issue tracking functionality](issues/index.md#issue-tracker) and
@@ -28,15 +59,12 @@ and deploy from one single platform. Issue Boards help you to visualize
 and manage the entire process _in_ GitLab.
 
 With [Multiple Issue Boards](#use-cases-for-multiple-issue-boards), available
-only in [GitLab Enterprise Edition](#features-per-tier),
+only in [different tiers of GitLab Enterprise Edition](#gitlab-enterprise-features-for-issue-boards),
 you go even further, as you can not only keep yourself and your project
 organized from a broader perspective with one Issue Board per project,
 but also allow your team members to organize their own workflow by creating
 multiple Issue Boards within the same project.
 
-For a visual overview, see our [Issue Board feature page](https://about.gitlab.com/features/issueboard/)
-on about.gitlab.com or our [video introduction to Issue Boards](https://www.youtube.com/watch?v=UWsJ8tkHAa8).
-
 ## Use cases
 
 There are many ways to use GitLab Issue Boards tailored to your own preferred workflow.
@@ -111,11 +139,6 @@ to improve their workflow with multiple boards.
 
 Create lists for each of your team members and quickly drag-and-drop issues onto each team member.
 
-## Permissions
-
-[Developers and up](../permissions.md) can use all the functionality of the
-Issue Board, that is, create or delete lists and drag issues from one list to another.
-
 ## Issue Board terminology
 
 - **Issue Board** - Each board represents a unique view for your issues. It can have multiple lists with each list consisting of issues represented by cards.
@@ -126,6 +149,139 @@ Issue Board, that is, create or delete lists and drag issues from one list to an
    - **Closed** (default): shows all closed issues. Always appears as the rightmost list.
 - **Card** - A box in the list that represents an individual issue. The information you can see on a card consists of the issue number, the issue title, the assignee, and the labels associated with the issue. You can drag cards from one list to another to change their label or assignee from that of the source list to that of the destination list.
 
+## Permissions
+
+[Developers and up](../permissions.md) can use all the functionality of the
+Issue Board, that is, create or delete lists and drag issues from one list to another.
+
+## GitLab Enterprise features for Issue Boards
+
+GitLab Issue Boards are available on GitLab Core and GitLab.com Free, but some
+advanced functionalities are only present in higher tiers: GitLab.com Bronze,
+Silver, or Gold, or GitLab self-managed Starter, Premium, and Ultimate, as described
+on the following sections.
+
+For a collection of [features per tier](#summary-of-features-per-tier), check the summary below.
+
+### Multiple Issue Boards **[STARTER]**
+
+> Introduced in [GitLab Enterprise Edition 8.13](https://about.gitlab.com/2016/10/22/gitlab-8-13-released/#multiple-issue-boards-ee).
+
+Multiple Issue Boards, as the name suggests, allow for more than one Issue Board
+for a given project or group. This is great for large projects with more than one team
+or in situations where a repository is used to host the code of multiple
+products.
+
+Clicking on the current board name in the upper left corner will reveal a
+menu from where you can create another Issue Board and rename or delete the
+existing one.
+
+NOTE: **Note:**
+The Multiple Issue Boards feature is available for
+**projects in GitLab Starter Edition** and for **groups in GitLab Premium Edition**.
+
+![Multiple Issue Boards](img/issue_boards_multiple.png)
+
+### Configurable Issue Boards **[STARTER]**
+
+> Introduced in [GitLab Starter Edition 10.2](https://about.gitlab.com/2017/11/22/gitlab-10-2-released/#issue-boards-configuration).
+
+An Issue Board can be associated with a GitLab [Milestone](milestones/index.md#milestones),
+[Labels](labels.md), Assignee and Weight
+which will automatically filter the Board issues according to these fields.
+This allows you to create unique boards according to your team's need.
+
+![Create scoped board](img/issue_board_creation.png)
+
+You can define the scope of your board when creating it or by clicking on the "Edit board" button. Once a milestone, assignee or weight is assigned to an Issue Board, you will no longer be able to filter
+through these in the search bar. In order to do that, you need to remove the desired scope (e.g. milestone, assignee or weight) from the Issue Board.
+
+![Edit board configuration](img/issue_board_edit_button.png)
+
+If you don't have editing permission in a board, you're still able to see the configuration by clicking on "View scope".
+
+![Viewing board configuration](img/issue_board_view_scope.png)
+
+### Focus mode **[STARTER]**
+
+> Introduced in [GitLab Starter 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep).
+
+Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board.
+
+![Board focus mode](img/issue_board_focus_mode.gif)
+
+### Sum of Issue Weights **[STARTER]**
+
+The top of each list indicates the sum of issue weights for the issues that
+belong to that list. This is useful when using boards for capacity allocation,
+especially in combination with [assignee lists](#assignee-lists).
+
+![Issue Board summed weights](img/issue_board_summed_weights.png)
+
+### Group Issue Boards **[PREMIUM]**
+
+> Introduced in [GitLab Premium 10.0](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards).
+
+Accessible at the group navigation level, a group issue board offers the same features as a project-level board,
+but it can display issues from all projects in that
+group and its descendant subgroups. Similarly, you can only filter by group labels for these
+boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only
+group-level objects are available.
+
+NOTE: **Note:**
+Multiple group issue boards were originally introduced in [GitLab 10.0 Premium](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards) and
+one group issue board per group was made available in GitLab 10.6 Core. 
+
+![Group issue board](img/group_issue_board.png)
+
+### Assignee lists **[PREMIUM]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5784) in GitLab 11.0 Premium.
+
+Like a regular list that shows all issues that have the list label, you can add
+an assignee list that shows all issues assigned to the given user.
+You can have a board with both label lists and assignee lists. To add an
+assignee list:
+
+1. Click **Add list**.
+1. Select the **Assignee list** tab.
+1. Search and click on the user you want to add as an assignee.
+
+Now that the assignee list is added, you can assign or unassign issues to that user
+by [dragging issues](#dragging-issues-between-lists) to and/or from an assignee list.
+To remove an assignee list, just as with a label list, click the trash icon.
+
+![Assignee lists](img/issue_board_assignee_lists.png)
+
+### Milestone lists **[PREMIUM]**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/6469) in GitLab 11.2 Premium.
+
+As of 11.2, you're also able to create lists of a milestone. As the name states,
+these are lists that filter issues by the assigned milestone, giving you more
+freedom and visibility on the Issue Board. To do so:
+
+1. Click **Add list**.
+1. Select the **Milestone** tab.
+1. Search and click on the milestone.
+
+Similar to the assignee lists, you're now able to [drag issues](#dragging-issues-between-lists)
+to and/or from a milestone list to manipulate the milestone of the dragged issues.
+As on another list types, click on the trash icon to remove it.
+
+![Milestone lists](img/issue_board_milestone_lists.png)
+
+### Summary of features per tier
+
+Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table:
+
+| Tier     | Number of Project Issue Boards | Number of Group Issue Boards | Configurable Issue Boards | Assignee Lists |
+|----------|--------------------------------|------------------------------|---------------------------|----------------|
+| Core / Free     | 1                              | 1                            | No                        | No             |
+| Starter / Bronze  | Multiple                       | 1                            | Yes                       | No             |
+| Premium / Silver | Multiple                       | Multiple                     | Yes                       | Yes            |
+| Ultimate / Gold | Multiple                       | Multiple                     | Yes                       | Yes            |
+
 ## Actions you can take on an Issue Board
 
 - [Create a new list](#creating-a-new-list).
@@ -142,7 +298,7 @@ Issue Board, that is, create or delete lists and drag issues from one list to an
 If you are not able to perform one or more of the things above, make sure you
 have the right [permissions](#permissions).
 
-## First time using the Issue Board
+### First time using the Issue Board
 
 The first time you navigate to your Issue Board, you will be presented with
 a default list (**Done**) and a welcoming message that gives
@@ -157,7 +313,7 @@ which means the system has no way of populating them automatically. That's of
 course if the predefined labels don't already exist. If any of them does exist,
 the list will be created and filled with the issues that have that label.
 
-## Creating a new list
+### Creating a new list
 
 Create a new list by clicking on the **Add list** button at the upper
 right corner of the Issue Board.
@@ -172,7 +328,7 @@ To create a list for a label that doesn't yet exist, simply create the label by
 choosing **Create new label**. The label will be created on-the-fly and it will
 be immediately added to the dropdown. You can now choose it to create a list.
 
-## Deleting a list
+### Deleting a list
 
 To delete a list from the Issue Board use the small trash icon that is present
 in the list's heading. A confirmation dialog will appear for you to confirm.
@@ -180,7 +336,7 @@ in the list's heading. A confirmation dialog will appear for you to confirm.
 Deleting a list doesn't have any effect in issues and labels, it's just the
 list view that is removed. You can always add it back later if you need.
 
-## Adding issues to a list
+### Adding issues to a list
 
 You can add issues to a list by clicking the **Add issues** button that is
 present in the upper right corner of the Issue Board. This will open up a modal
@@ -192,7 +348,7 @@ the list by filtering by author, assignee, milestone and label.
 
 ![Bulk adding issues to lists](img/issue_boards_add_issues_modal.png)
 
-## Removing an issue from a list
+### Removing an issue from a list
 
 Removing an issue from a list can be done by clicking on the issue card and then
 clicking the **Remove from board** button in the sidebar. Under the hood, the
@@ -201,7 +357,7 @@ board itself.
 
 ![Remove issue from list](img/issue_boards_remove_issue.png)
 
-## Issue ordering in a list
+### Issue ordering in a list
 
 When visiting a board, issues appear ordered in any list. You are able to change
 that order simply by dragging and dropping the issues. The changed order will be saved
@@ -224,7 +380,7 @@ a given board inside your GitLab instance, any time those two issues are subsequ
 loaded in any board in the same instance (could be a different project board or a different group board, for example),
 that ordering will be maintained.
 
-## Filtering issues
+### Filtering issues
 
 You should be able to use the filters on top of your Issue Board to show only
 the results you want. This is similar to the filtering used in the issue tracker
@@ -232,7 +388,7 @@ since the metadata from the issues and labels are re-used in the Issue Board.
 
 You can filter by author, assignee, milestone and label.
 
-## Creating workflows
+### Creating workflows
 
 By reordering your lists, you can create workflows. As lists in Issue Boards are
 based on labels, it works out of the box with your existing issues. So if you've
@@ -267,89 +423,7 @@ to another list the label changes and a system not is recorded.
 
 ![Issue Board system notes](img/issue_board_system_notes.png)
 
-## Multiple Issue Boards **[STARTER]**
-
-> Introduced in [GitLab Enterprise Edition 8.13](https://about.gitlab.com/2016/10/22/gitlab-8-13-released/#multiple-issue-boards-ee).
-
-Multiple Issue Boards, as the name suggests, allow for more than one Issue Board
-for a given project or group. This is great for large projects with more than one team
-or in situations where a repository is used to host the code of multiple
-products.
-
-Clicking on the current board name in the upper left corner will reveal a
-menu from where you can create another Issue Board and rename or delete the
-existing one.
-
-NOTE: **Note:**
-The Multiple Issue Boards feature is available for
-**projects in GitLab Starter Edition** and for **groups in GitLab Premium Edition**.
-
-![Multiple Issue Boards](img/issue_boards_multiple.png)
-
-## Configurable Issue Boards **[STARTER]**
-
-> Introduced in [GitLab Starter Edition 10.2](https://about.gitlab.com/2017/11/22/gitlab-10-2-released/#issue-boards-configuration).
-
-An Issue Board can be associated with GitLab [Milestone](milestones/index.md#milestones),
-[Labels](labels.md), Assignee and Weight
-which will automatically filter the Board issues according to these fields.
-This allows you to create unique boards according to your team's need.
-
-![Create scoped board](img/issue_board_creation.png)
-
-You can define the scope of your board when creating it or by clicking on the "Edit board" button. Once a milestone, assignee or weight is assigned to an Issue Board, you will no longer be able to filter
-through these in the search bar. In order to do that, you need to remove the desired scope (e.g. milestone, assignee or weight) from the Issue Board.
-
-![Edit board configuration](img/issue_board_edit_button.png)
-
-If you don't have editing permission in a board, you're still able to see the configuration by clicking on "View scope".
-
-![Viewing board configuration](img/issue_board_view_scope.png)
-
-## Focus mode **[STARTER]**
-
-> Introduced in [GitLab Starter 9.1](https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep).
-
-Click the button at the top right to toggle focus mode on and off. In focus mode, the navigation UI is hidden, allowing you to focus on issues in the board.
-
-![Board focus mode](img/issue_board_focus_mode.gif)
-
-## Group Issue Boards **[PREMIUM]**
-
-> Introduced in [GitLab Premium 10.0](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards).
-
-Accessible at the group navigation level, a group issue board offers the same features as a project-level board,
-but it can display issues from all projects in that
-group and its descendant subgroups. Similarly, you can only filter by group labels for these
-boards. When updating milestones and labels for an issue through the sidebar update mechanism, again only
-group-level objects are available.
-
-NOTE: **Note:**
-Multiple group issue boards were originally introduced in [GitLab 10.0 Premium](https://about.gitlab.com/2017/09/22/gitlab-10-0-released/#group-issue-boards) and
-one group issue board per group was made available in GitLab 10.6 Core. 
-
-![Group issue board](img/group_issue_board.png)
-
-## Assignee lists **[PREMIUM]**
-
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/5784) in GitLab 11.0 Premium.
-
-Like a regular list that shows all issues that have the list label, you can add
-an assignee list that shows all issues assigned to the given user.
-You can have a board with both label lists and assignee lists. To add an
-assignee list:
-
-1. Click **Add list**.
-1. Select the **Assignee list** tab.
-1. Search and click on the user you want to add as an assignee.
-
-Now that the assignee list is added, you can assign or unassign issues to that user
-by [dragging issues](#dragging-issues-between-lists) to and/or from an assignee list.
-To remove an assignee list, just as with a label list, click the trash icon.
-
-![Assignee lists](img/issue_board_assignee_lists.png)
-
-## Dragging issues between lists
+### Dragging issues between lists
 
 When dragging issues between lists, different behavior occurs depending on the source list and the target list.
 
@@ -360,17 +434,6 @@ When dragging issues between lists, different behavior occurs depending on the s
 | From label `A` list        | `A` removed        | Issue closed | `A` removed<br/>`B` added    | `Bob` assigned                        |
 | From assignee `Alice` list | `Alice` unassigned | Issue closed | `B` added                    | `Alice` unassigned<br/>`Bob` assigned |
 
-## Features per tier
-
-Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/), as shown in the following table:
-
-| Tier     | Number of Project Issue Boards | Number of Group Issue Boards | Configurable Issue Boards | Assignee Lists |
-|----------|--------------------------------|------------------------------|---------------------------|----------------|
-| Core     | 1                              | 1                            | No                        | No             |
-| Starter  | Multiple                       | 1                            | Yes                       | No             |
-| Premium  | Multiple                       | Multiple                     | Yes                       | Yes            |
-| Ultimate | Multiple                       | Multiple                     | Yes                       | Yes            |
-
 ## Tips
 
 A few things to remember: