4 files changed, 71 insertions, 27 deletions

diff --git a/doc/development/feature_flags/controls.md b/doc/development/feature_flags/controls.md
index 7551199aa58..adcf3175c45 100644
--- a/doc/development/feature_flags/controls.md
+++ b/doc/development/feature_flags/controls.md
@@ -250,6 +250,7 @@ Changes to the issue format can be submitted in the
 Any feature flag change that affects any GitLab instance is automatically logged in
 [features_json.log](../../administration/logs.md#features_jsonlog).
 You can search the change history in [Kibana](https://about.gitlab.com/handbook/support/workflows/kibana.html).
+You can access the feature flag change history for GitLab.com [here](https://log.gprd.gitlab.net/goto/d060337c017723084c6d97e09e591fc6).
 
 ## Cleaning up
 
diff --git a/doc/development/feature_flags/development.md b/doc/development/feature_flags/development.md
index 7c5333c9aa6..dd732a08c72 100644
--- a/doc/development/feature_flags/development.md
+++ b/doc/development/feature_flags/development.md
@@ -378,6 +378,18 @@ You can also enable a feature flag for a given gate:
 Feature.enable(:feature_flag_name, Project.find_by_full_path("root/my-project"))
 ```
 
+### Removing a feature flag locally (in development)
+
+When manually enabling or disabling a feature flag from the Rails console, its default value gets overwritten.
+This can cause confusion when changing the flag's `default_enabled` attribute.
+
+To reset the feature flag to the default status, you can remove it in the rails console (`rails c`)
+as follows:
+
+```ruby
+Feature.remove(:feature_flag_name)
+```
+
 ## Feature flags in tests
 
 Introducing a feature flag into the codebase creates an additional code path that should be tested.
diff --git a/doc/development/feature_flags/index.md b/doc/development/feature_flags/index.md
index 270e07ed755..e93a5b3de1b 100644
--- a/doc/development/feature_flags/index.md
+++ b/doc/development/feature_flags/index.md
@@ -6,24 +6,34 @@ info: "See the Technical Writers assigned to Development Guidelines: https://abo
 
 # Feature flags in development of GitLab
 
+**NOTE**:
+The documentation below covers feature flags used by GitLab to deploy its own features, which **is not** the same
+as the [feature flags offered as part of the product](../../operations/feature_flags.md).
+
 ## When to use feature flags
 
-Starting with GitLab 11.4, developers are required to use feature flags for
-non-trivial changes. Such changes include:
+Developers are required to use feature flags for changes that could affect availability of existing GitLab functionality (if it only affects the new feature you're making that is probably acceptable).
+Such changes include:
+
+1. New features in high traffic areas (e.g. a new merge request widget, new option in issues/epics, new CI functionality).
+1. Complex performance improvements that may require additional testing in production (e.g. rewriting complex queries, changes to frequently used API endpoints).
+1. Invasive changes to the user interface (e.g. introducing a new navigation bar, removal of a sidebar, UI element change in issues or MR interface).
+1. Introducing dependencies on third-party services (e.g. adding support for importing projects).
+1. Changes to features that can cause data corruption or cause data loss (e.g. features processing repository data or user uploaded content).
+
+Situations where you might consider not using a feature flag:
+
+1. Adding a new API endpoint
+1. Introducing new features in low traffic areas (e.g. adding a new export functionality in the admin area/group settings/project settings)
+1. Non-invasive frontend changes (e.g. changing the color of a button, or moving a UI element in a low traffic area)
+
+In all cases, those working on the changes should ask themselves:
 
-- New features (e.g. a new merge request widget, epics, etc).
-- Complex performance improvements that may require additional testing in
-  production, such as rewriting complex queries.
-- Invasive changes to the user interface, such as a new navigation bar or the
-  removal of a sidebar.
-- Adding support for importing projects from a third-party service.
-- Risk of data loss
+> Why do I need to add a feature flag? If I don't add one, what options do I have to control the impact on application reliability, and user experience?
 
-In all cases, those working on the changes can best decide if a feature flag is
-necessary. For example, changing the color of a button doesn't need a feature
-flag, while changing the navigation bar definitely needs one. In case you are
-uncertain if a feature flag is necessary, simply ask about this in the merge
-request, and those reviewing the changes will likely provide you with an answer.
+For perspective on why we limit our use of feature flags please see the following [video](https://www.youtube.com/watch?v=DQaGqyolOd8). 
+
+In case you are uncertain if a feature flag is necessary, simply ask about this in an early merge request, and those reviewing the changes will likely provide you with an answer.
 
 When using a feature flag for UI elements, make sure to _also_ use a feature
 flag for the underlying backend code, if there is any. This ensures there is
@@ -36,35 +46,29 @@ they are new features or performance improvements. By using feature flags,
 you can determine the impact of GitLab-directed changes, while still being able
 to disable those changes without having to revert an entire release.
 
-Before using feature flags for GitLab development, review the following development guides:
-
-NOTE:
-The feature flags used by GitLab to deploy its own features **are not** the same
-as the [feature flags offered as part of the product](../../operations/feature_flags.md).
-
 For an overview about starting with feature flags in GitLab development,
 use this [training template](https://gitlab.com/gitlab-com/www-gitlab-com/-/blob/master/.gitlab/issue_templates/feature-flag-training.md).
 
-Development guides:
+Before using feature flags for GitLab development, review the following development guides:
 
-- [Process for using features flags](process.md): When you should use
+1. [Process for using features flags](process.md): When you should use
   feature flags in the development of GitLab, what's the cost of using them,
   and how to include them in a release.
-- [Developing with feature flags](development.md): Learn about the types of
+1. [Developing with feature flags](development.md): Learn about the types of
   feature flags, their definition and validation, how to create them, frontend and
   backend details, and other information.
-- [Documenting features deployed behind feature flags](../documentation/feature_flags.md):
+1. [Documenting features deployed behind feature flags](../documentation/feature_flags.md):
   How to document features deployed behind feature flags, and how to update the
   documentation for features' flags when their states change.
-- [Controlling feature flags](controls.md): Learn the process for deploying
+1. [Controlling feature flags](controls.md): Learn the process for deploying
   a new feature, enabling it on GitLab.com, communicating the change,
   logging, and cleaning up.
 
 User guides:
 
-- [How GitLab administrators can enable and disable features behind flags](../../administration/feature_flags.md):
+1. [How GitLab administrators can enable and disable features behind flags](../../administration/feature_flags.md):
   An explanation for GitLab administrators about how they can
   enable or disable GitLab features behind feature flags.
-- [What "features deployed behind flags" means to the GitLab user](../../user/feature_flags.md):
+1. [What "features deployed behind flags" means to the GitLab user](../../user/feature_flags.md):
   An explanation for GitLab users regarding how certain features
   might not be available to them until they are enabled.
diff --git a/doc/development/feature_flags/process.md b/doc/development/feature_flags/process.md
index 2e3680bb103..7e6299c193c 100644
--- a/doc/development/feature_flags/process.md
+++ b/doc/development/feature_flags/process.md
@@ -148,3 +148,30 @@ they speed up the process as managing incidents now becomes _much_ easier. Once
 continuous deployments are easier to perform, the time to iterate on a feature
 is reduced even further, as you no longer need to wait weeks before your changes
 are available on GitLab.com.
+
+### The benefits of feature flags
+
+It may seem like feature flags are configuration, which goes against our [convention-over-configuration](https://about.gitlab.com/handbook/product/product-principles/#convention-over-configuration)
+principle. However, configuration is by definition something that is user-manageable.
+Feature flags are not intended to be user-editable. Instead, they are intended as a tool for Engineers
+and Site Reliability Engineers to use to de-risk their changes. Feature flags are the shim that gets us
+to Continuous Delivery with our mono repo and without having to deploy the entire codebase on every change. 
+Feature flags are created to ensure that we can safely rollout our work on our terms.
+If we use Feature Flags as a configuration, we are doing it wrong and are indeed in violation of our
+principles. If something needs to be configured, we should intentionally make it configuration from the
+first moment.
+
+Some of the benefits of using development-type feature flags are:
+
+1. It enables Continuous Delivery for GitLab.com.
+1. It significantly reduces Mean-Time-To-Recovery.
+1. It helps engineers to monitor and reduce the impact of their changes gradually, at any scale,
+   allowing us to be more metrics-driven and execute good DevOps practices, [shifting some responsibility "left"](https://devops.com/why-its-time-for-site-reliability-engineering-to-shift-left/).
+1. Controlled feature rollout timing: without feature flags, we would need to wait until a specific
+   deployment was complete (which at GitLab could be at any time).
+1. Increased psychological safety: when a feature flag is used, an engineer has the confidence that if anything goes wrong they can quickly disable the code and minimize the impact of a change that might be risky.
+1. Improved throughput: when a change is less risky because a flag exists, theoretical tests about
+   scalability can potentially become unnecessary or less important. This allows an engineer to
+   potentially test a feature on a small project, monitor the impact, and proceed. The alternative might
+   be to build complex benchmarks locally, or on staging, or on another GitLab deployment, which has an
+   outsized impact on the time it can take to build and release a feature.