diff --git a/x-pack/docs/en/security/authentication/file-realm.asciidoc b/x-pack/docs/en/security/authentication/file-realm.asciidoc
index 8603500954a..010c5348008 100644
--- a/x-pack/docs/en/security/authentication/file-realm.asciidoc
+++ b/x-pack/docs/en/security/authentication/file-realm.asciidoc
@@ -7,17 +7,21 @@ With the `file` realm, users are defined in local files on each node in the clus
 
 IMPORTANT:  As the administrator of the cluster, it is your responsibility to
 ensure the same users are defined on every node in the cluster. The {stack}
-{security-features} do not deliver any mechanism to guarantee this.
+{security-features} do not deliver any mechanism to guarantee this. You should
+also be aware that you cannot add or manage users in the `file` realm via the
+<<security-user-apis, user APIs>> and you cannot add or manage them in {kib} on the
+*Management / Security / Users* page
 
-The `file` realm is primarily supported to serve as a fallback/recovery realm. It
-is mostly useful in situations where all users locked themselves out of the system
-(no one remembers their username/password). In this type of scenarios, the `file`
-realm is your only way out - you can define a new `admin` user in the `file` realm
-and use it to log in and reset the credentials of all other users.
+The `file` realm is very useful as a fallback or recovery realm. For example in cases where
+the cluster is unresponsive or the security index is unavailable, or when you forget the
+password for your administrative users.
+In this type of scenario, the `file` realm is a convenient way out - you can
+define a new `admin` user in the `file` realm and use it to log in and reset the
+credentials of all other users.
 
 IMPORTANT: When you configure realms in `elasticsearch.yml`, only the realms you
-specify are used for authentication. To use the `file` realm as a fallback, you
-must include it in the realm chain.
+specify are used for authentication. To use the `file` realm you must explicitly
+include it in the realm chain.
 
 To define users, the {security-features} provide the
 {ref}/users-command.html[users] command-line tool. This tool enables you to add