Improve Issue Boards docs

doc/.vale/gitlab/spelling-exceptions.txt

@@ -76,6 +76,7 @@ Citus
 clonable
 Cloudwatch
 Cobertura
+Codepen
 Cognito
 colocated
 colocating

doc/api/boards.md

@@ -455,7 +455,7 @@ POST /projects/:id/boards/:board_id/lists
 NOTE: **Note:**
 Label, assignee and milestone arguments are mutually exclusive,
 that is, only one of them are accepted in a request.
-Check the [Issue Board docs](../user/project/issue_board.md#summary-of-features-per-tier)
+Check the [Issue Board docs](../user/project/issue_board.md)
 for more information regarding the required license for each list type.
 
 ```shell

doc/user/project/issue_board.md

@@ -15,59 +15,45 @@ organize, and visualize a workflow for a feature or product release.
 It can be used as a [Kanban](https://en.wikipedia.org/wiki/Kanban_(development)) or a
 [Scrum](https://en.wikipedia.org/wiki/Scrum_(software_development)) board.
 
-It pairs 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.
+It pairs 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.
 
-With issue boards, you organize your issues in lists that correspond to
-their assigned labels, visualizing issues designed as cards throughout those lists.
+Issue boards build on the existing [issue tracking functionality](issues/index.md#issues-list) and
+[labels](labels.md). Your issues appear as cards in vertical lists, organized by their assigned
+labels, [milestones](#milestone-lists), or [assignees](#assignee-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.
+Issue boards help you to visualize and manage your entire process in GitLab.
+You add your labels, and then create the corresponding list for your existing issues.
+When you're ready, you can drag your issue cards from one step to another one.
 
-![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
-the Issue Board feature (introduced in GitLab 8.11 - August 2016).
-
-### Advanced features of issue boards
-
-- Create multiple issue boards per project.
-- Create multiple issue boards per group. **(PREMIUM)**
-- Add lists for [assignees](#assignee-lists) and [milestones](#milestone-lists). **(PREMIUM)**
-
-Check all the [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards).
+An issue board can show you what issues your team is working on, who is assigned to each,
+and where in the workflow those issues are.
 
-![GitLab issue boards - Premium](img/issue_boards_premium.png)
+To let your team members organize their own workflows, use
+[multiple issue boards](#use-cases-for-multiple-issue-boards). This allows creating multiple issue
+boards in the same project.
 
-## How it works
+![GitLab issue board - Core](img/issue_boards_core.png)
 
-The Issue Board feature builds on GitLab's existing
-[issue tracking functionality](issues/index.md#issues-list) and
-[labels](labels.md) by using them as lists of the Scrum board.
+Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/),
+as shown in the following table:
 
-With issue boards you can have a different view of your issues while
-maintaining the same filtering and sorting abilities you see across the
-issue tracker. An issue board is based on its project's label structure, so it
-applies the same descriptive labels to indicate placement on the board, keeping
-consistency throughout the entire development lifecycle.
+| Tier             | Number of project issue boards | Number of [group issue boards](#group-issue-boards) | [Configurable issue boards](#configurable-issue-boards) | [Assignee lists](#assignee-lists) |
+|------------------|--------------------------------|------------------------------|---------------------------|----------------|
+| Core / Free      | Multiple                       | 1                            | No                        | No             |
+| Starter / Bronze | Multiple                       | 1                            | Yes                       | No             |
+| Premium / Silver | Multiple                       | Multiple                     | Yes                       | Yes            |
+| Ultimate / Gold  | Multiple                       | Multiple                     | Yes                       | Yes            |
 
-An issue board shows you what issues your team is working on, who is assigned to each,
-and where in the workflow those issues are.
+To learn more, visit [GitLab Enterprise features for issue boards](#gitlab-enterprise-features-for-issue-boards) below.
 
-You create issues, host code, perform reviews, build, test,
-and deploy from one single platform. Issue boards help you to visualize
-and manage the entire process in GitLab.
+![GitLab issue board - Premium](img/issue_boards_premium.png)
 
-With [multiple issue boards](#use-cases-for-multiple-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.
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+Watch a [video presentation](https://youtu.be/vjccjHI7aGI) of
+the Issue Board feature.
 
-## Use cases
+## Issue boards use cases
 
 You can tailor GitLab issue boards to your own preferred workflow.
 Here are some common use cases for issue boards.
@@ -138,8 +124,7 @@ to improve their workflow with multiple boards.
 
 #### Quick assignments
 
-Create lists for each of your team members and quickly drag and drop issues onto each team member's
-list.
+Create lists for each of your team members and quickly drag issues onto each team member's list.
 
 ## Issue board terminology
 
@@ -172,22 +157,36 @@ card includes:
 Users with the [Reporter and higher roles](../permissions.md) can use all the functionality of the
 Issue Board feature to create or delete lists and drag issues from one list to another.
 
-## GitLab Enterprise features for issue boards
+## How GitLab orders issues in a list
 
-GitLab issue boards are available on GitLab Core and GitLab.com Free tiers, but some
-advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/).
+When visiting a board, issues appear ordered in any list. You're able to change
+that order by dragging the issues. The changed order is saved, so that anybody who visits the same
+board later sees the reordering, with some exceptions.
 
-### Summary of features per tier
+The first time a given issue appears in any board (that is, the first time a user
+loads a board containing that issue), it is ordered in relation to other issues in that list
+according to [label priority](labels.md#label-priority).
 
-Different issue board features are available in different [GitLab tiers](https://about.gitlab.com/pricing/),
-as shown in the following table:
+At this point, that issue is assigned a relative order value by the system,
+representing its relative order with respect to the other issues in the list. Any time
+you reorder that issue by dragging, its relative order value changes accordingly.
 
-| Tier             | Number of Project issue boards | Number of Group issue boards | Configurable issue boards | Assignee lists |
-|------------------|--------------------------------|------------------------------|---------------------------|----------------|
-| Core / Free      | Multiple                       | 1                            | No                        | No             |
-| Starter / Bronze | Multiple                       | 1                            | Yes                       | No             |
-| Premium / Silver | Multiple                       | Multiple                     | Yes                       | Yes            |
-| Ultimate / Gold  | Multiple                       | Multiple                     | Yes                       | Yes            |
+Also, any time that issue appears in any board when it's loaded by a user,
+the updated relative order value is used for the ordering. It's only the first
+time an issue appears that it takes from the priority order mentioned above. This means that
+if issue `A` is reordered by dragging to be above issue `B` by any user in
+a given board inside your GitLab instance, any time those two issues are subsequently
+loaded in any board in the same instance (could be a different project board or a different group
+board, for example), that ordering is maintained.
+
+This ordering also affects [issue lists](issues/sorting_issue_lists.md).
+Changing the order in an issue board changes the ordering in an issue list,
+and vice versa.
+
+## GitLab Enterprise features for issue boards
+
+GitLab issue boards are available on GitLab Core and GitLab.com Free tiers, but some
+advanced functionality is present in [higher tiers only](https://about.gitlab.com/pricing/).
 
 ### Multiple issue boards
 
@@ -248,6 +247,10 @@ clicking **View scope**.
 
 ![Viewing board configuration](img/issue_board_view_scope.png)
 
+<i class="fa fa-youtube-play youtube" aria-hidden="true"></i>
+Watch a [video presentation](https://youtu.be/m5UTNCSqaDk) of
+the Configurable Issue Board feature.
+
 ### Focus mode
 
 > - [Introduced]((https://about.gitlab.com/releases/2017/04/22/gitlab-9-1-released/#issue-boards-focus-mode-ees-eep)) in [GitLab Starter](https://about.gitlab.com/pricing/) 9.1.
@@ -362,7 +365,6 @@ status.
 - [Create workflows](#create-workflows).
 - [Drag issues between lists](#drag-issues-between-lists).
 - [Multi-select issue cards](#multi-select-issue-cards).
-- [Re-order issues in lists](#issue-ordering-in-a-list).
 - Drag and reorder the lists.
 - Change issue labels (by dragging an issue between lists).
 - Close an issue (by dragging it to the **Done** list).
@@ -441,8 +443,9 @@ You can filter by author, assignee, milestone, and label.
 ### Create 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
-already labeled things with 'Backend' and 'Frontend', the issue appears in
+based on labels, it works out of the box with your existing issues.
+
+So if you've already labeled things with **Backend** and **Frontend**, the issue appears in
 the lists as you create them. In addition, this means you can easily move
 something between lists by changing a label.
 
@@ -456,20 +459,22 @@ A typical workflow of using an issue board would be:
 1. You move issues around in lists so that your team knows who should be working
    on what issue.
 1. When the work by one team is done, the issue can be dragged to the next list
-   so someone else can pick up.
+   so someone else can pick it up.
 1. When the issue is finally resolved, the issue is moved to the **Done** list
    and gets automatically closed.
 
-For instance you can create a list based on the label of 'Frontend' and one for
-'Backend'. A designer can start working on an issue by adding it to the
-'Frontend' list. That way, everyone knows that this issue is now being
-worked on by the designers. Then, once they're done, all they have to do is
-drag it over to the next list, 'Backend', where a backend developer can
+For example, you can create a list based on the label of **Frontend** and one for
+**Backend**. A designer can start working on an issue by adding it to the
+**Frontend** list. That way, everyone knows that this issue is now being
+worked on by the designers.
+
+Then, once they're done, all they have to do is
+drag it to the next list, **Backend**, where a backend developer can
 eventually pick it up. Once they’re done, they move it to **Done**, to close the
 issue.
 
 This process can be seen clearly when visiting an issue since with every move
-to another list the label changes and a system not is recorded.
+to another list the label changes and a system note is recorded.
 
 ![issue board system notes](img/issue_board_system_notes.png)
 
@@ -497,33 +502,6 @@ To select and move multiple cards:
 
 ![Multi-select Issue Cards](img/issue_boards_multi_select_v12_4.png)
 
-### Issue ordering in a list
-
-When visiting a board, issues appear ordered in any list. You're able to change
-that order by dragging and dropping the issues. The changed order will be saved
-to the system so that anybody who visits the same board later will see the reordering,
-with some exceptions.
-
-The first time a given issue appears in any board (that is, the first time a user
-loads a board containing that issue), it is ordered with
-respect to other issues in that list according to [Priority order](labels.md#label-priority).
-
-At that point, that issue is assigned a relative order value by the system
-representing its relative order with respect to the other issues in the list. Any time
-you drag-and-drop reorder that issue, its relative order value changes accordingly.
-
-Also, any time that issue appears in any board when it's loaded by a user,
-the updated relative order value is used for the ordering. (It's only the first
-time an issue appears that it takes from the Priority order mentioned above.) This means that
-if issue `A` is drag-and-drop reordered to be above issue `B` by any user in
-a given board inside your GitLab instance, any time those two issues are subsequently
-loaded in any board in the same instance (could be a different project board or a different group
-board, for example), that ordering is maintained.
-
-This ordering also affects [issue lists](issues/sorting_issue_lists.md).
-Changing the order in an issue board changes the ordering in an issue list,
-and vice versa.
-
 ## Tips
 
 A few things to remember:
@@ -537,4 +515,4 @@ A few things to remember:
   and show only the issues from all lists that have that label.
 - For performance and visibility reasons, each list shows the first 20 issues
   by default. If you have more than 20 issues, start scrolling down and the next
-  20 appears.
+  20 appear.

doc/user/project/issues/sorting_issue_lists.md

@@ -11,7 +11,7 @@ etc. The available sorting options can change based on the context of the list.
 For sorting by issue priority, see [Label Priority](../labels.md#label-priority).
 
 In group and project issue lists, it is also possible to order issues manually,
-similar to [issue boards](../issue_board.md#issue-ordering-in-a-list).
+similar to [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list).
 
 ## Manual sorting
 
@@ -31,6 +31,6 @@ a given list inside your GitLab instance, any time those two issues are subseque
 loaded in any list in the same instance (could be a different project issue list or a
 different group issue list, for example), that ordering will be maintained.
 
-This ordering also affects [issue boards](../issue_board.md#issue-ordering-in-a-list).
+This ordering also affects [issue boards](../issue_board.md#how-gitlab-orders-issues-in-a-list).
 Changing the order in an issue list changes the ordering in an issue board,
 and vice versa.