From 78a81c1be41ebf4530566160c08d8aa92ab20be5 Mon Sep 17 00:00:00 2001
From: Patrik Oldsberg <poldsberg@gmail.com>
Date: Sun, 24 Jan 2021 18:16:39 +0100
Subject: [PATCH] docs/conf: update config writing docs to talk about includes
 instead of secrets

---
 docs/conf/index.md   |  4 ++--
 docs/conf/writing.md | 44 +++++++++++++++++++++-----------------------
 2 files changed, 23 insertions(+), 25 deletions(-)

diff --git a/docs/conf/index.md b/docs/conf/index.md
index a6f1d1f6f7..ef6faffd8b 100644
--- a/docs/conf/index.md
+++ b/docs/conf/index.md
@@ -18,8 +18,8 @@ allowing for customization.
 Configuration is stored in YAML files where the defaults are `app-config.yaml`
 and `app-config.local.yaml` for local overrides. Other sets of files can by
 loaded by passing `--config <path>` flags. The configuration files themselves
-contain plain YAML, but with support for loading in secrets from various sources
-using for example `$env` and `$file` keys.
+contain plain YAML, but with support for loading in data and secrets from
+various sources using for example `$env` and `$file` keys.
 
 It is also possible to supply configuration through environment variables, for
 example `APP_CONFIG_app_baseUrl=https://staging.example.com`. However these
diff --git a/docs/conf/writing.md b/docs/conf/writing.md
index 7e8402b6f6..05babd66d5 100644
--- a/docs/conf/writing.md
+++ b/docs/conf/writing.md
@@ -97,13 +97,13 @@ order:
 - If no config flags are provided, `app-config.local.yaml` has higher priority
   than `app-config.yaml`.
 
-## Secrets and Dynamic Data
+## Includes and Dynamic Data
 
-Secrets are supported via special data loading keys that are prefixed with `$`,
-which in turn provide a number of different ways to read in secrets. To load a
-configuration value as a secret, supply an object with one of the special secret
-keys, for example `$env` or `$file`. A full list of supported secret keys can be
-found below. For example, the following will read the config key
+Includes are supported via special data loading keys that are prefixed with `$`,
+which in turn provide a number of different ways to read in data. To load in an
+external configuration value, supply an object with one of the special include
+keys, for example `$env` or `$file`. A full list of supported include keys can
+be found below. For example, the following will read the config key
 `backend.mySecretKey` from the environment variable `MY_SECRET_KEY`:
 
 ```yaml
@@ -114,28 +114,26 @@ backend:
 
 With the above configuration, calling `config.getString('backend.mySecretKey')`
 will return the value of the environment variable `MY_SECRET_KEY` when the
-backend started up. All secrets are loaded at startup, so changing the contents
-of secret files or environment variables will not be reflected at runtime.
+backend started up. All includes are loaded at startup, so changing the contents
+of files or environment variables will not be reflected at runtime.
 
-As hinted at, secrets can be loaded from a bunch of different sources, and can
-be extended with more. Below is a list of the currently supported methods for
-loading secrets.
+Below is a list of the currently supported methods for loading includes.
 
-### Env Secrets
+### Env Includes
 
-This reads a secret from an environment variable. For example, the following
-config loads the secret from the `MY_SECRET` env var.
+This reads a string value from an environment variable. For example, the
+following configuration loads the string value from the `MY_SECRET` environment
+variable.
 
 ```yaml
 $env: MY_SECRET
 ```
 
-### File Secrets
+### File Includes
 
-This reads a secret from the entire contents of a file. The file path is
-relative to the `app-config.yaml` the defines the secrets. For example, the
-following reads the contents of `my-secret.txt` relative to the config file
-itself:
+This reads a string value from the entire contents of a text file. The file path
+is relative to the source config file. For example, the following reads the
+contents of `my-secret.txt` relative to the config file itself:
 
 ```yaml
 $file: ./my-secret.txt
@@ -143,10 +141,10 @@ $file: ./my-secret.txt
 
 ### Including Files
 
-The `$include` keyword can be used to load in JSON data from an external file.
-It's able to load and parse data from `.json`, `.yml`, and `.yaml` files. It's
-also possible to include a url fragment (`#`) to point to a value at the given
-path in the file.
+The `$include` keyword can be used to load configuration values from an external
+file. It's able to load and parse data from `.json`, `.yml`, and `.yaml` files.
+It's also possible to include a url fragment (`#`) to point to a value at the
+given path in the file, using a dot-separated list of keys.
 
 For example, the following would read `my-secret-key` from `my-secrets.json`: