From fedd698c09688e935862d81ed91936b316f54a5b Mon Sep 17 00:00:00 2001 From: Karen Miller <84039272+KMiller-Grafana@users.noreply.github.com> Date: Wed, 9 Feb 2022 00:18:27 -0800 Subject: [PATCH] Docs: Incorporate parameter categories into the config reference (#1128) --- ...bout-configuration-parameter-categories.md | 27 ------------------- .../reference-configuration-parameters.md | 26 ++++++++++++++++++ ...eference-configuration-parameters.template | 26 ++++++++++++++++++ 3 files changed, 52 insertions(+), 27 deletions(-) delete mode 100644 docs/sources/configuration/about-configuration-parameter-categories.md diff --git a/docs/sources/configuration/about-configuration-parameter-categories.md b/docs/sources/configuration/about-configuration-parameter-categories.md deleted file mode 100644 index 7aa5061181c..00000000000 --- a/docs/sources/configuration/about-configuration-parameter-categories.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -title: "About configuration parameter categories" -description: "" -weight: 10 ---- - -# About configuration parameter categories - -In order to simplify Mimir configuration, parameters are bucketed into 3 categories according to -their maturity and intended use: _basic_, _advanced_, and _experimental_. - -## Basic - -Parameters that we expect the majority of users to modify. For example, object store credentials or -other dependency connection information. These parameters will generally remain stable for long periods -of time, and should focus on user goals. - -## Advanced - -Parameters that we expect the majority of users to leave defaulted, but we have evidence that there -are strong use-cases to change the default value. - -## Experimental - -Parameters related to new and experimental features under testing. These parameters are provided -for users who wish to become early adopters and for Mimir developers to gain confidence with new -features. diff --git a/docs/sources/configuration/reference-configuration-parameters.md b/docs/sources/configuration/reference-configuration-parameters.md index 3a99bdefad9..8e3a4869481 100644 --- a/docs/sources/configuration/reference-configuration-parameters.md +++ b/docs/sources/configuration/reference-configuration-parameters.md @@ -36,6 +36,32 @@ brackets indicate that a parameter is optional. - `2006-01-20T15:04` (local timezone) - RFC 3339 formats: `2006-01-20T15:04:05Z` (UTC) or `2006-01-20T15:04:05+07:00` (explicit timezone) +## Parameter categories + +In order to simplify Mimir configuration, we categorize parameters by +maturity level and intended use: + +- **Basic** parameters are ones that we expect the majority of users to modify. + Examples of basic parameters are object store credentials and + other dependency connection information. + These parameters will generally remain stable for long periods of time, + and they focus on user goals. + In this reference, any parameters that are not marked as `(advanced)` or + `(experimental)` are in the basic category. + +- **Advanced** parameters are ones that few users will change + from their default values. + There are strong use cases for altered values. + In this reference, advanced-category parameters include `(advanced)` at + the beginning of their description. + +- **Experimental** parameters are for new and experimental features. + These parameters permit + early adopters and Mimir developers to gain confidence with new + features. + In this reference, experimental-category parameters include `(experimental)` at + the beginning of their description. + ## Use environment variables in the configuration You can use environment variable references in the YAML configuration file diff --git a/docs/sources/configuration/reference-configuration-parameters.template b/docs/sources/configuration/reference-configuration-parameters.template index 55bdbdbb0c3..988b434c09d 100644 --- a/docs/sources/configuration/reference-configuration-parameters.template +++ b/docs/sources/configuration/reference-configuration-parameters.template @@ -36,6 +36,32 @@ brackets indicate that a parameter is optional. - `2006-01-20T15:04` (local timezone) - RFC 3339 formats: `2006-01-20T15:04:05Z` (UTC) or `2006-01-20T15:04:05+07:00` (explicit timezone) +## Parameter categories + +In order to simplify Mimir configuration, we categorize parameters by +maturity level and intended use: + +- **Basic** parameters are ones that we expect the majority of users to modify. +Examples of basic parameters are object store credentials and +other dependency connection information. +These parameters will generally remain stable for long periods of time, +and they focus on user goals. +In this reference, any parameters that are not marked as `(advanced)` or +`(experimental)` are in the basic category. + +- **Advanced** parameters are ones that few users will change +from their default values. +There are strong use cases for altered values. +In this reference, advanced-category parameters include `(advanced)` at +the beginning of their description. + +- **Experimental** parameters are for new and experimental features. +These parameters permit +early adopters and Mimir developers to gain confidence with new +features. +In this reference, experimental-category parameters include `(experimental)` at +the beginning of their description. + ## Use environment variables in the configuration You can use environment variable references in the YAML configuration file