Merge branch 'docs/scoped-labels' into 'master'

Add more info about scoped labels

See merge request gitlab-org/gitlab-ee!11253

doc/user/project/labels.md

@@ -12,11 +12,40 @@ In GitLab, you can create project and group labels:
 - **Group labels** can be assigned to any issue or merge request of any project in that group or any subgroups of the group.
 
 ## Scoped labels **[PREMIUM]**
-A scoped label is a specific kind of label defined only by a special colon syntax in the label’s title, namely `key::value`. There is no different way to create and otherwise manage scoped labels. A label is a scoped label when its title follows the syntax.
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/9175) in [GitLab Premium](https://about.gitlab.com/pricing/) 11.10.
+
+Scoped labels allow teams to use the simple and familiar feature of labels to
+annotate their issues, merge requests, and epics to achieve custom fields and
+custom workflow states, by leveraging a special label title syntax to create those scopes.
+
+A scoped label is a specific kind of label defined only by a special colon syntax
+in the label’s title, namely `key::value`.
 
 ![A sample scoped label](img/key_value_labels.png)
 
-A scoped label with a same key but with different value cannot be applied together to an Issue, Epic or a Merge Request. For example, if an issue has `priority::3` already and you apply `priority::2` to it, `priority::3` automatically gets removed from the issue.
+A scoped label with a same key but with different value cannot be applied together
+to an issue, epic or a merge request. For example, if an issue has `priority::3`
+already and you apply `priority::2` to it, `priority::3` automatically gets removed
+from the issue.
+
+### Workflows with scoped labels **[PREMIUM]**
+
+Suppose you wanted a custom field in issues to track the platform operating system
+that your features target, and each issue should only target one platform. You
+would then create labels `platform::iOS`, `platform::Android`, `platform::Linux`,
+etc., as necessary. Applying any one of these labels on a given issue would
+automatically remove any other existing label that starts with `platform::`.
+
+The same pattern could be applied to represent the workflow states of your teams.
+Suppose you have the labels `workflow::development`, `workflow::review`, and
+`workflow::deployed`. If an issue already has the label `workflow::development`
+applied, and a developer wanted to advance the issue to `workflow::review`, they
+would simply apply that label, and the `workflow::development` label would
+automatically be removed. This behavior already exists when you move issues
+across label lists in an [issue board](issue_board.md#creating-workflows), but
+now team members who may not be working in an issue board directly, would still
+nonetheless be able to advance workflow states consistently in issues themselves.
 
 ## Creating labels
 
@@ -56,12 +85,6 @@ From the sidebar of an issue or a merge request, you can create a create a new *
 
 ![Labels inline](img/new_label_from_sidebar.gif)
 
-### New scoped label
-
-To create a scoped label, follow similar steps from above. The only difference is to include double-colon `::` character in the title of the Label when created or edited.
-
-In the case where labels have multiple sets of `::`, the longest path is used as the key. For example, we would check for exclusivity on `some::key::` level instead of `some::` on label `some::key::value`.
-
 ## Editing labels
 
 NOTE: **Note:**