Merge branch 'docs/add-features-burndown-charts' into 'master'

Add new doc to Burndown Charts + use cases

See merge request !2364

doc/README.md

@@ -93,7 +93,7 @@ Manage files and branches from the UI (user interface):
   - [Checkout merge requests locally](user/project/merge_requests/index.md#checkout-merge-requests-locally)
   - [Cherry-pick](user/project/merge_requests/cherry_pick_changes.md)
 - [Milestones](user/project/milestones/index.md): Organize issues and merge requests into a cohesive group, optionally setting a due date.
-  - **(EES/EEP)** [Burndown Charts](user/project/milestones/index.md#burndown-charts): Watch your project's progress throughout a specific milestone.
+  - **(EES/EEP)** [Burndown Charts](user/project/milestones/burndown_charts.md): Watch your project's progress throughout a specific milestone.
 - [Related issues](user/project/issues/related_issues.md)
 - [Todos](workflow/todos.md): A chronological list of to-dos that are waiting for your input, all in a simple dashboard.
 

doc/user/project/milestones/burndown_charts.md

+# Burndown Charts
+
+>**Notes:**
+- [Introduced][ee-1540] in [GitLab Enterprise Edition Starter 9.1][ee-9.1].
+- Closed or reopened issues prior to GitLab 9.1 won't have a `closed_at`
+  value, so the burndown chart considers them as closed on the milestone
+  `start_date`. In that case, a warning will be displayed.
+
+## Overview
+
+Burndown Charts are visual representations of the progress of completing a milestone.
+
+![burndown chart](img/burndown_chart.png)
+
+At a glance, you see the current state for the completion a given milestone.
+Without them, you would have to organize the data from the milestone and plot it
+yourself to have the same sense of progress.
+
+GitLab Enterprise Edition Starter plots it for you and presents it in a clear and beautiful chart.
+
+## Use cases
+
+Burndown Charts, in gerenal, are used for tracking and analyzing the completion of
+a milestone. Therefore, their use cases are tied to the
+[use you are giving to your milestone](index.md#use-cases).
+
+To exemplify, suppose you lead a team of developers in a large company,
+and you follow this workflow:
+
+- Your company set the goal for the quarter to deliver 10 new features for your app
+in the upcoming major release
+- You create a milestone, and remind your team to assign that milestone to every new issue
+and merge request that's part of the launch of your app
+- Every week, you open the milestone, visualize the progress, identify the gaps,
+and help your team to get their work done
+- Every month, you check in with your supervisor, and show the progress of that milestone
+from the Burndown Chart
+- By the end of the quarter, your team successfully delivered 100% of that milestone, as
+it was taken care of closely throughout the whole quarter
+
+## How it works
+
+A Burndown Chart is available for every project milestone that has been attributed a **start
+date** and a **due date**.
+
+Find your project's **Burndown Chart** under **Project > Issues > Milestones**,
+and select a milestone from your current ones.
+
+The chart indicates the project's progress throughout that milestone (for issues assigned to it).
+
+In particular, it shows how many issues were or are still open for a given day in the
+milestone's corresponding period.
+
+Since it only tracks when an issue was last closed (and not its full history), the chart
+assumes that issue was open on days prior to that date. Reopened issues are
+considered as open on one day after they were closed.
+
+Note that with this design, if you create a new issue in the middle of the milestone period 
+(and assign the milestone to the issue), the Burndown Chart will appear as if the 
+issue was already open at the beginning of the milestone. A workaround is to simply 
+close the issue (so that a closed timestamp is stored in the system), and reopen 
+it to ge the desired effect, with a rise in the chart appearing on the day after.
+This is what appears in the example below.
+
+The Burndown Chart can also be toggled to display the cumulative open issue
+weight for a given day. When using this feature, make sure issue weights have
+been properly assigned, since an open issue with no weight adds zero to the
+cumulative value.
+
+[ee-1540]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1540
+[ee-9.1]: https://about.gitlab.com/2017/04/22/gitlab-9-1-released/#burndown-charts-ees-eep

doc/user/project/milestones/index.md

 # Milestones
 
+Milestones in GitLab are a way to track issues and merge requests created
+to achieve a broader goal in a certain period of time.
+
+## Overview
+
 Milestones allow you to organize issues and merge requests into a cohesive group,
-optionally setting a due date. A common use is keeping track of an upcoming
-software version. Milestones can be created per-project or per-group.
+optionally setting a start and a due date.
+
+With milestones you can set a deadline for certain achievement you're targeting,
+and assign this milestone to issues and merge requests that together compose
+this broader goal.
+
+Milestones are a valuable tool to track the development of the process of achieving that goal.
+From a milestone, you view the status of issues and merge requests, its contributors,
+and opened and closed issues for each label.
+
+With [GitLab Enterprise Edition Starter](https://about.gitlab.com/gitlab-ee/),
+you will also see a [Burndown Chart](#burndown-charts) for your milestone, which
+gives a visual insight over the progress of the conclusion of that milestone:
+
+![milestones with burndown charts](img/milestones.gif)
+
+## Use cases
+
+There are numerous cases you can create a milestone for. For example:
+
+- Track an upcoming software version
+- Track the launch of a new product
+- Track the progress of achievements per quarter for your team
+- Track the community contribution for a new feature in your open source application
 
 ## Creating a project milestone
 
@@ -56,39 +83,10 @@ total merge requests and issues.
 
 ![Milestone statistics](img/progress.png)
 
-## Burndown charts
-
->**Notes:**
-- [Introduced][ee-1540] in GitLab Enterprise Edition 9.1 and is available for
-  [Enterprise Edition Starter][ee] users.
-- Closed or reopened issues prior to GitLab 9.1 won't have a `closed_at`
-  value, so the burndown chart considers them as closed on the milestone
-  `start_date`. In that case, a warning will be displayed.
-
-A burndown chart is available for every project milestone that has a set start
-date and a set due date and is located on the project's milestone page.
-
-It indicates the project's progress throughout that milestone (for issues that
-have that milestone assigned to it). In particular, it shows how many issues
-were or are still open for a given day in the milestone period. Since GitLab
-only tracks when an issue was last closed (and not its full history), the chart
-assumes that issue was open on days prior to that date. Reopened issues are
-considered as open on one day after they were closed.
-
-Note that with this design, if you create a new issue in the middle of the milestone period 
-(and assign the milestone to the issue), the burndown chart will appear as if the 
-issue was already open at the beginning of the milestone. A workaround is to simply 
-close the issue (so that a closed timestamp is stored in the system), and reopen 
-it to ge the desired effect, with a rise in the chart appearing on the day after.
-This is what appears in the example below.
-
-The burndown chart can also be toggled to display the cumulative open issue
-weight for a given day. When using this feature, make sure your weights have
-been properly assigned, since an open issue with no weight adds zero to the
-cumulative value.
+## Burndown Charts
 
-![burndown chart](img/burndown_chart.png)
-
-[ee-1540]: https://gitlab.com/gitlab-org/gitlab-ee/merge_requests/1540
-[ee]: https://about.gitlab.com/gitlab-ee
+[Burndown Charts](burndown_charts.md), available in
+[GitLab Enterprise Edition Starter](https://about.gitlab.com/gitlab-ee),
+are visual representations of the progress of completing a milestone.
 
+![burndown chart](img/burndown_chart.png)