Add latest changes from gitlab-org/gitlab@master

3 files changed, 83 insertions, 21 deletions

diff --git a/doc/user/analytics/cycle_analytics.md b/doc/user/analytics/cycle_analytics.md
index 377af433342..7a966f92934 100644
--- a/doc/user/analytics/cycle_analytics.md
+++ b/doc/user/analytics/cycle_analytics.md
@@ -1,27 +1,27 @@
 # Cycle Analytics
 
-> - Introduced prior to GitLab 12.2 at the project level.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12077) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.2 at the group level.
-
-NOTE: **Note:**
-As of GitLab 12.3 this feature is enabled by the `cycle_analytics` feature flag.
+> - Introduced prior to GitLab 12.3 at the project level.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12077) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3 at the group level.
 
 Cycle Analytics measures the time spent to go from an [idea to production] - also known
 as cycle time - for each of your projects. Cycle Analytics displays the median time for an idea to
 reach production, along with the time typically spent in each DevOps stage along the way.
 
+NOTE: **Note:**
+Use the `cycle_analytics` feature flag to enable at the group level.
+
 Cycle Analytics is useful in order to quickly determine the velocity of a given
 project. It points to bottlenecks in the development process, enabling management
 to uncover, triage, and identify the root cause of slowdowns in the software development life cycle.
 
-Cycle Analytics is tightly coupled with the [GitLab flow] and
-calculates a separate median for each stage.
+Cycle Analytics is tightly coupled with the [GitLab flow] and calculates a separate median for each
+stage.
 
 ## Overview
 
 Cycle Analytics is available:
 
-- From GitLab 12.2, at the group level in the analytics workspace at
+- From GitLab 12.3, at the group level in the analytics workspace (top navigation bar) at
   **Analytics > Cycle Analytics**. **(PREMIUM)**
 
   In the future, multiple groups will be selectable which will effectively make this an
@@ -147,19 +147,19 @@ A few notes:
 
 The current permissions on the Project Cycle Analytics dashboard are:
 
-- Public projects - anyone can access
-- Internal projects - any authenticated user can access
-- Private projects - any member Guest and above can access
+- Public projects - anyone can access.
+- Internal projects - any authenticated user can access.
+- Private projects - any member Guest and above can access.
 
 You can [read more about permissions][permissions] in general.
 
 NOTE: **Note:**
-As of GitLab 12.2, the project-level page is deprecated. You should access
+As of GitLab 12.3, the project-level page is deprecated. You should access
 project-level Cycle Analytics from **Analytics > Cycle Analytics** in the top
 navigation bar. We will ensure that the same project-level functionality is available
 to CE users in the new analytics space.
 
-For Cycle Analytics functionality introduced in GitLab 12.2 and later:
+For Cycle Analytics functionality introduced in GitLab 12.3 and later:
 
 - Users must have Reporter access or above.
 - Features are available only on
@@ -173,8 +173,8 @@ Learn more about Cycle Analytics in the following resources:
 - [Cycle Analytics feature preview](https://about.gitlab.com/2016/09/16/feature-preview-introducing-cycle-analytics/)
 - [Cycle Analytics feature highlight](https://about.gitlab.com/2016/09/21/cycle-analytics-feature-highlight/)
 
-[ce-5986]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/5986
-[ce-20975]: https://gitlab.com/gitlab-org/gitlab-ce/issues/20975
+[ce-5986]: https://gitlab.com/gitlab-org/gitlab-foss/merge_requests/5986
+[ce-20975]: https://gitlab.com/gitlab-org/gitlab-foss/issues/20975
 [environment]: ../../ci/yaml/README.md#environment
 [GitLab flow]: ../../workflow/gitlab_flow.md
 [idea to production]: https://about.gitlab.com/2016/08/05/continuous-integration-delivery-and-deployment-with-gitlab/#from-idea-to-production-with-gitlab
diff --git a/doc/user/analytics/index.md b/doc/user/analytics/index.md
index ba2735dc324..8e88d8fd7b6 100644
--- a/doc/user/analytics/index.md
+++ b/doc/user/analytics/index.md
@@ -1,21 +1,31 @@
 # Analytics workspace
 
-> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12077) in GitLab 12.2.
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/issues/12077) in GitLab 12.2.
 
 The Analytics workspace will make it possible to aggregate analytics across
 GitLab, so that users can view information across multiple projects and groups
 in one place.
 
-To access the centralized analytics workspace, click on **Analytics** from the top navigation bar.
+To access the centralized analytics workspace, enable at least
+[one of the features](#available-analytics) under the workspace.
+
+Once enabled, click on **Analytics** from the top navigation bar.
 
 ## Available analytics
 
 From the centralized analytics workspace, the following analytics are available:
 
-- [Cycle Analytics](cycle_analytics.md):
-
-1. Requires a GitLab administrator to enable it with the `cycle_analytics` feature flag.
-1. Once enabled, click on **Analytics** and then **Cycle Analytics** from the top navigation bar.
+- [Cycle Analytics](cycle_analytics.md), enabled with the `cycle_analytics`
+  [feature flag](../../development/feature_flags/development.html#enabling-a-feature-flag-in-development). **(PREMIUM)**
+- [Productivity Analytics](productivity_analytics.md), enabled with the `productivity_analytics`
+  [feature flag](../../development/feature_flags/development.html#enabling-a-feature-flag-in-development). **(PREMIUM)**
 
 NOTE: **Note:**
 Project-level Cycle Analytics are still available at a project's **Project > Cycle Analytics**.
+
+## Other analytics tools
+
+In addition to the tools available in the Analytics workspace, GitLab provides:
+
+- [Contribution analytics](../group/contribution_analytics/index.md). **(STARTER)**
+- [Issue analytics](../group/issues_analytics/index.md). **(PREMIUM)**
diff --git a/doc/user/analytics/productivity_analytics.md b/doc/user/analytics/productivity_analytics.md
new file mode 100644
index 00000000000..a53ef56bbf7
--- /dev/null
+++ b/doc/user/analytics/productivity_analytics.md
@@ -0,0 +1,52 @@
+# Productivity Analytics **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/12079) in [GitLab Premium](https://about.gitlab.com/pricing/) 12.3 (enabled by feature flags `productivity_analytics`).
+
+Track development velocity with Productivity Analytics.
+
+For many companies, the development cycle is a blackbox and getting an estimate of how
+long, on average, it takes to deliver features is an enormous endeavor.
+
+While [Cycle Analytics](../project/cycle_analytics.md) focuses on the entire
+Software Development Life Cycle (SDLC) process, Productivity Analytics provides a way for Engineering Management to drill down in a systematic way to uncover patterns and causes for success or failure at an individual, project or group level.
+
+Productivity can slow down for many reasons ranging from degrading code base to quickly growing teams. In order to investigate, department or team leaders can start by visualizing the time it takes for merge requests to be merged.
+
+## Supported features
+
+Productivity Analytics allows GitLab users to:
+
+- Visualize typical merge request (MR) lifetime and statistics. Use a histogram that shows the distribution of the time elapsed between creating and merging merge requests.
+- Drill down into the most time consuming merge requests, select a number of outliers, and filter down all subsequent charts to investigate potential causes.
+- Filter by group, project, author, label, milestone, or a specific date range. Filter down, for example, to the merge requests of a specific author in a group or project during a milestone or specific date range.
+- Measure velocity over time. Visualize the trends of each metric from the charts above over time in order to observe progress. Zoom in on a particular date range if you notice outliers.
+
+## Accessing metrics and visualizations
+
+To access the **Productivity Analytics** page:
+
+1. Go to **Analytics** from the top navigation bar.
+1. Select **Productivity Analytics** from the menu.
+
+The following metrics and visualizations are available on a project or group level - currently only covering **merged** merge requests:
+
+- Histogram showing the number of merge request that took a specified number of days to merge after creation. Select a specific column to filter down subsequent charts.
+- Histogram showing a breakdown of the time taken (in hours) to merge a merge request. The following intervals are available:
+  - Time from first commit to first comment.
+  - Time from first comment until last commit.
+  - Time from last commit to merge.
+- Histogram showing the size or complexity of a merge request, using the following:
+  - Number of commits per merge request.
+  - Number of lines of code per commit.
+  - Number of files touched.
+- Scatterplot showing all MRs merged on a certain date, together with the days it took to complete the action and a 30 day rolling median.
+  - Users can zoom in and out on specific days of interest.
+- Table showing list of merge requests with their respective times and size metrics.
+  - Users can sort by any of the above metrics.
+
+## Permissions
+
+The **Productivity Analytics** dashboard can be accessed only:
+
+- On [Premium or Silver tier](https://about.gitlab.com/pricing/) and above.
+- By users with [Reporter access](../permissions.md) and above.