Resolve EE diff in PROCESS.mdmj/feature-flags-doc

Resolve few broken doc links in fe guide and apply suggestions

8 files changed, 42 insertions, 38 deletions

diff --git a/PROCESS.md b/PROCESS.md
index 25e9834df01..22b68b0aaca 100644
--- a/PROCESS.md
+++ b/PROCESS.md
@@ -92,15 +92,21 @@ Guides on how to include feature flags in your backend/frontend code while devel
 
 Getting access and how to expose the feature to users is detailed in [controlling feature flags documentation](https://docs.gitlab.com/ee/development/feature_flags/controls.html).
 
+## Feature proposals from the 22nd to the 1st
+
+To allow the Product and Engineering teams time to discuss issues that will be placed into an upcoming milestone,
+Product Managers must have their proposal for that milestone ready by the 22nd of each month.
+
+This proposal will be shared with Engineering for discussion, feedback, and planning.
+The plan for the upcoming milestone must be finalized by the 1st of the month, one week before kickoff on the 8th.
+
 ## Feature freeze on the 7th for the release on the 22nd
 
-The feature freeze on the 7th has been discontinued. [Transition period overview]
+The feature freeze on the 7th has been discontinued. [Transition period overview](https://gitlab.com/gitlab-org/release/docs/blob/21cbd409dd5f157fe252f254f3e897f01908abe2/general/deploy/auto-deploy-transition.md#transition)
 describes the change to this process. During the transition period, the only guarantee that
 a change will be included in the release on the 22nd is if the change has been
 deployed to GitLab.com prior to this date.
 
-[Transition period]: https://gitlab.com/gitlab-org/release/docs/blob/21cbd409dd5f157fe252f254f3e897f01908abe2/general/deploy/auto-deploy-transition.md#transition
-
 ### Between the 1st and the 7th
 
 These types of merge requests for the upcoming release need special consideration:
diff --git a/doc/development/chatops_on_gitlabcom.md b/doc/development/chatops_on_gitlabcom.md
index 28dc7b80fb1..a7b402c3fb0 100644
--- a/doc/development/chatops_on_gitlabcom.md
+++ b/doc/development/chatops_on_gitlabcom.md
@@ -1,6 +1,6 @@
 # Chatops on GitLab.com
 
-Chatops on GitLab.com allows GitLab team-members to run various automation tasks on GitLab.com using Slack.
+ChatOps on GitLab.com allows GitLab team members to run various automation tasks on GitLab.com using Slack.
 
 ## Requesting access
 
@@ -19,4 +19,4 @@ To request access to Chatops on GitLab.com:
 
  - [Chatops Usage](https://docs.gitlab.com/ee/ci/chatops/README.html)
  - [Understanding EXPLAIN plans](understanding_explain_plans.md)
- - [Feature Groups](feature_flags.md#feature-groups)
+ - [Feature Groups](feature_flags/development.md#feature-groups)
diff --git a/doc/development/feature_flags.md b/doc/development/feature_flags.md
index 38f6b7f81ae..6bad91d6287 100644
--- a/doc/development/feature_flags.md
+++ b/doc/development/feature_flags.md
@@ -1,5 +1 @@
-This document has been moved to:
-
-* [feature flags process documentation](https://docs.gitlab.com/ee/development/feature_flags/process.html).
-* [developing with feature flags documentation](https://docs.gitlab.com/ee/development/feature_flags/developing.html).
-* [controlling feature flags documentation](https://docs.gitlab.com/ee/development/feature_flags/controls.html).
+This document was moved to [another location](feature_flags/index.md).
diff --git a/doc/development/feature_flags/developing.md b/doc/development/feature_flags/development.md
index 238052529d9..238052529d9 100644
--- a/doc/development/feature_flags/developing.md
+++ b/doc/development/feature_flags/development.md
diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md
new file mode 100644
index 00000000000..56872f8c075
--- /dev/null
+++ b/doc/development/feature_flags/index.md
@@ -0,0 +1,12 @@
+# Feature flags in development of GitLab
+
+Feature flags can be used to gradually roll out changes, be
+it a new feature, or a performance improvement. By using feature flags, we can
+comfortably measure the impact of our changes, while still being able to easily
+disable those changes, without having to revert an entire release.
+
+Before using feature flags for GitLab's development, read through the following:
+
+- [Process for using features flags](process.md).
+- [Developing with feature flags documentation](development.md).
+- [Controlling feature flags documentation](controls.md).
diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md
index be3472ee71f..ee142b0da66 100644
--- a/doc/development/feature_flags/process.md
+++ b/doc/development/feature_flags/process.md
@@ -1,10 +1,4 @@
-# Feature flags in development of GitLab
-
-Feature flags can be used to gradually roll out changes, be
-it a new feature, or a performance improvement. By using feature flags, we can
-comfortably measure the impact of our changes, while still being able to easily
-disable those changes, without having to revert an entire release.
-
+# Feature flags process
 ## Feature flags for user applications
 
 This document only covers feature flags used in the development of GitLab
@@ -16,13 +10,13 @@ itself. Feature flags in deployed user applications can be found at
 The following highlights should be considered when deciding if feature flags
 should be leveraged:
 
-* By default, the feature flags should be **off**.
-* Feature flags should remain in the codebase for as short period as possible
+- By default, the feature flags should be **off**.
+- Feature flags should remain in the codebase for as short period as possible
 to reduce the need for feature flag accounting.
-* Person operating with feature flags is responsible for clearly communicating
+- The person operating with feature flags is responsible for clearly communicating
 the status of a feature behind the feature flag with responsible stakeholders.
-* Merge requests that make changes hidden behind a feature flag, or remove an
-existing feature flag because a feature is deemed stable should have the
+- Merge requests that make changes hidden behind a feature flag, or remove an
+existing feature flag because a feature is deemed stable must have the
 ~"feature flag" label assigned.
 
 One might be tempted to think that feature flags will delay the release of a
@@ -69,12 +63,12 @@ to be included in the final self-managed release.
 
 In addition to this, the feature behind feature flag should:
 
-* Run in all GitLab.com environments for a sufficient period of time. This time
+- Run in all GitLab.com environments for a sufficient period of time. This time
 period depends on the feature behind the feature flag, but as a general rule of
 thumb 2-4 working days should be sufficient to gather enough feedback.
-* The feature should be exposed to all users within the GitLab.com plan during
+- The feature should be exposed to all users within the GitLab.com plan during
 the above mentioned period of time. Exposing the feature to a smaller percentage
-or only a group of users might not expose sufficient amount of information to aid
+or only a group of users might not expose a sufficient amount of information to aid in
 making a decision on feature stability.
 
 While rare, release managers may decide to reject picking or revert a change in
@@ -95,8 +89,8 @@ Let's say we are building a new feature, and we have determined that the cost of
 this is 10. We have also determined that the cost of adding a feature flag check
 in a variety of places is 1. If we do not use feature flags, and our feature
 works as intended, our total cost is 10. This however is the best case scenario.
-Optimising for the best case scenario is guaranteed to lead to trouble, whereas
-optimising for the worst case scenario is almost always better.
+Optimizing for the best case scenario is guaranteed to lead to trouble, whereas
+optimizing for the worst case scenario is almost always better.
 
 To illustrate this, let's say our feature causes an outage, and there's no
 immediate way to resolve it. This means we'd have to take the following steps to
@@ -115,7 +109,7 @@ many developers, and worst of all: our users will have a bad experience using
 GitLab.com until the problem is resolved.
 
 Now let's say that all of this has an associated cost of 10. This means that in
-the worst case scenario, which we should optimise for, our total cost is now 20.
+the worst case scenario, which we should optimize for, our total cost is now 20.
 
 If we had used a feature flag, things would have been very different. We don't
 need to revert a release, and because feature flags are disabled by default we
diff --git a/doc/development/new_fe_guide/tips.md b/doc/development/new_fe_guide/tips.md
index 4564f678ec0..879b54bd93c 100644
--- a/doc/development/new_fe_guide/tips.md
+++ b/doc/development/new_fe_guide/tips.md
@@ -10,16 +10,16 @@ yarn clean
 
 ## Creating feature flags in development
 
-The process for creating a feature flag is the same as [enabling a feature flag in development](../feature_flags.md#enabling-a-feature-flag-in-development).
+The process for creating a feature flag is the same as [enabling a feature flag in development](../feature_flags/development.md#enabling-a-feature-flag-in-development).
 
 Your feature flag can now be:
 
-- [made available to the frontend](../feature_flags.md#frontend) via the `gon`
-- queried in [tests](../feature_flags.md#specs)
-- queried in HAML templates and ruby files via the `Feature.enabled?(:my_shiny_new_feature_flag)` method
+- [Made available to the frontend](../feature_flags/development.md#frontend) via the `gon`
+- Queried in [tests](../feature_flags/development.md#specs)
+- Queried in HAML templates and ruby files via the `Feature.enabled?(:my_shiny_new_feature_flag)` method
 
 ### More on feature flags
 
 - [Deleting a feature flag](../../api/features.md#delete-a-feature)
-- [Manage feature flags](../feature_flags.md)
+- [Manage feature flags](../feature_flags/process.md)
 - [Feature flags API](../../api/features.md)
diff --git a/doc/development/rolling_out_changes_using_feature_flags.md b/doc/development/rolling_out_changes_using_feature_flags.md
index 38f6b7f81ae..6bad91d6287 100644
--- a/doc/development/rolling_out_changes_using_feature_flags.md
+++ b/doc/development/rolling_out_changes_using_feature_flags.md
@@ -1,5 +1 @@
-This document has been moved to:
-
-* [feature flags process documentation](https://docs.gitlab.com/ee/development/feature_flags/process.html).
-* [developing with feature flags documentation](https://docs.gitlab.com/ee/development/feature_flags/developing.html).
-* [controlling feature flags documentation](https://docs.gitlab.com/ee/development/feature_flags/controls.html).
+This document was moved to [another location](feature_flags/index.md).