diff --git a/libbeat/docs/shared-feature-flags.asciidoc b/libbeat/docs/shared-feature-flags.asciidoc
index cf53cd626f7..42f74b449ca 100644
--- a/libbeat/docs/shared-feature-flags.asciidoc
+++ b/libbeat/docs/shared-feature-flags.asciidoc
@@ -1,16 +1,24 @@
 [[configuration-feature-flags]]
-== Configure Feature Flags
+== Configure feature flags
 
 ++++
-<titleabbrev>Feature Flags</titleabbrev>
+<titleabbrev>Feature flags</titleabbrev>
 ++++
 
-Example configuration with the FQDN feature flag enabled:
+The Feature Flags section of the +{beatname_lc}.yml+ config file contains
+settings in {beatname_uc} that are disabled by default. These may include 
+experimental features, changes to behaviors within {beatname_uc}, or 
+settings that could cause a breaking change. For example a
+setting that changes information included in events might be inconsistent with
+the naming pattern expected in your configured {beatname_uc} output.
 
-["source","yaml"]
+To enable any of the settings listed on this page, change the associated `enabled`
+flag from `false` to `true`.
+
+[source,yaml]
 ----
 features:
-  fqdn:
+  mysetting:
     enabled: true
 ----
 
@@ -22,8 +30,27 @@ You can specify the following options in the `features` section of the +{beatnam
 [float]
 ==== `fqdn`
 
-Contains configuration for the FQDN reporting feature.  When this feature is enabled, {beatname_uc} will
-report the fully-qualified domain name for the host on which it's running.
+Contains configuration for the FQDN reporting feature. When this feature is
+enabled, the fully-qualified domain name for the host is reported in the
+`host.name` field in events produced by {beatname_uc}.
+
+For FQDN reporting to work as expected, the hostname of the current host must either:
+
+* Have a CNAME entry defined in DNS.
+* Have one of its corresponding IP addresses respond successfully to a reverse
+DNS lookup.
+
+If neither pre-requisite is satisfied, `host.name` continues to report the
+hostname of the current host as if the FQDN feature flag were not enabled.
+
+Example configuration:
+
+[source,yaml]
+----
+features:
+  fqdn:
+    enabled: true
+----
 
 [float]
 ===== `enabled`