Great refactor of Issue Board docs

3 files changed, 89 insertions, 10 deletions

diff --git a/doc/user/project/img/issue_board.png b/doc/user/project/img/issue_board.png
new file mode 100644
index 00000000000..accd0900cbb
--- /dev/null
+++ b/doc/user/project/img/issue_board.png
diff --git a/doc/user/project/issue_board.md b/doc/user/project/issue_board.md
index 5890c48013f..29c823a68f3 100644
--- a/doc/user/project/issue_board.md
+++ b/doc/user/project/issue_board.md
@@ -4,15 +4,96 @@
 
 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 seen like a light version of a [Kanban] or a [Scrum] board.
 
-It allows you to create lists, which are based on the [labels] that already
-exist in the issue tracker. Issues can be seen as cards and they can easily be
+## Overview
+
+The Issue Board builds on GitLab's existing issue tracking functionality and
+leverages the power of [labels] by utilizing them as lists of the scrum board.
+
+With the Issue Board you can have a different view of your issues while also
+maintaining the same filtering and sorting abilities you see across the
+issue tracker.
+
+There are three types of lists, of which two are default:
+
+- **Backlog** (default): shows all issues that do not fall in one of the other
+  lists. Always appears on the very left.
+- **Done** (default): shows all closed issues. Always appears on the very right.
+- Label list: a list based on a label. It shows all issues with that label.
+
+![GitLab Issue Board](img/issue_board.png)
+
+---
+
+Below is a table of the definitions used for GitLab's Issue Board.
+
+| Term | Definition |
+| ---- | ----------- |
+| **Issue Board** | It can have up to 10 lists with each list consisting of issues represented by cards. |
+| **List** | Each label that exists in the issue tracker can have its own dedicated list. Every list is named after the label it is based on and is represented by a column which contains all the issues associated with that label. You can think of a list like the results you get when you filter the issues by a label in your issue tracker. You can create up to 10 lists per Issue Board. |
+| **Card** | Every card represents an issue. The information you can see on a card consists of the issue number, the issue title and the labels associated with it. You can drag cards around from one lists to another. Issues are [ordered by priority](labels.md#prioritize-labels). |
+
+
+## Functionality
+
+The Issue Board consists of lists appearing as columns. Each list is named after
+and based on the labels that already exist in your issue tracker.
+
+It allows you to create lists, which are based on the labels that already
+exist in your issue tracker. Issues can be seen as cards and they can easily be
 moved between the lists, as to create workflows.
 
+Every list contains all issues that are associated with the corresponding label.
+
+The issues inside each list are sorted by priority.
+
+- Issue boards can have between 2-10 lists which display as columns.
+
+The first time you navigate to your Issue Board, you will be presented with the
+two special lists ('Backlog' and 'Done') and a welcoming message that
 The starting point is two lists: **Backlog** and **Done**. Under the **Backlog**
 list, all the issues that are not assigned to a list will appear. Drag a card
 to the **Done** list and the relevant issue will be closed.
 
+Here's a list of actions you can take in an Issue Board:
+
+1. Create a new issue list
+1. Delete an issue list
+1. Drag issues between lists
+1. Drag and reorder the lists themselves
+1. Change issue labels on-the-fly while dragging issues between lists
+1. Close an issue if you drag it to the 'Done' list
+1. Create a new list from a non-existing label by creating the label on-the-fly
+1. Populate lists with issues automatically
+
+Issues > Labels
+
+Board > Lists > Cards
+
+Moving an issue between lists removes the label from the list it came from (exception: backlog) and adds the label of the list it goes to:
+
+When moving from the backlog, just add the new label. The backlog is not a label.
+
+When moving to Done, remove the label of the list it came from and close the issue.
+
+If an issue exists in multiple label lists, just show it in multiple lists:
+
+
+## First time using the Issue Board
+
+When default lists are created, they are empty because the labels associated to them did not exist up until that moment, which means the system has no way of populating them automatically. It'll be the users' job to add individual issues to them.
+
+## Adding a new list
+
+Add a new list by clicking on the button. In a modal you will find a label dropdown, where you can also create new labels (like in the sidebar):
+
+The new list should be inserted at the end of the lists, before Done.
+
+## Moving lists
+
+You should be able to drag the label lists around by dragging them on the top.
+
 ## Creating workflows
 
 By adding new lists, you can create workflows. For instance you can create a
@@ -31,15 +112,12 @@ you can easily move something between lists by changing a label.
 If you move an issue from one list to the next, it removes the label from the
 list it comes from and adds the label from the list it moves towards.
 
-## Pro-tips
+## Filtering issues
 
-- Issue boards can have between 2-10 lists which display as columns.
-- Creating a new list is easy! Simply click the **Create new list** button in
-  the upper right corner and select the labels from your GitLab issue tracker
-  to populate the list.
-- If you need to create a list based on a label that doesn't exist yet, just
-  click **Create new list** and then "Create new**.
-- All issues can be dragged and dropped into lists.
+You should be able to use the filters on top, as seen in the mockup and similar to the issue list.
+Every issue contains metadata.
 
 [ce-5554]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5554
 [labels]: ./labels.md
+[scrum]: https://en.wikipedia.org/wiki/Scrum_(software_development)
+[kanban]: https://en.wikipedia.org/wiki/Kanban_(development)
diff --git a/doc/workflow/README.md b/doc/workflow/README.md
index 1653d95e722..8979600735a 100644
--- a/doc/workflow/README.md
+++ b/doc/workflow/README.md
@@ -6,6 +6,7 @@
 - [Feature branch workflow](workflow.md)
 - [GitLab Flow](gitlab_flow.md)
 - [Groups](groups.md)
+- [Issue Board](../user/project/issue_board.md)
 - [Keyboard shortcuts](shortcuts.md)
 - [Slash commands](slash_commands.md)
 - [File finder](file_finder.md)