Docs: Add section on configuration parameter categories #938

aknuds1 · 2022-01-28T09:53:08Z

What this PR does:
Add documentation section on configuration parameter categories.

Which issue(s) this PR fixes:
Fixes #910.

Checklist

[na] Tests updated
Documentation added
[na] CHANGELOG.md updated - the order of entries should be [CHANGE], [FEATURE], [ENHANCEMENT], [BUGFIX]

aknuds1 · 2022-01-28T09:54:28Z

docs/sources/configuration/config-param-lifecycle.md

+---
+title: "Configuration parameter lifecycle"
+linkTitle: "Configuration parameter lifecycle"
+weight: 1


I need input on what the weight should be.

Weighting should be in magnitudes of 10 or 100 (to allow for future content). Lower weights appear higher in the TOC

And thank you for asking this question - we'll add it to our writing guidelines.

@GrafanaWriter I was more wondering what the weight should be in relation to the other sections, i.e. where to put this section in the ordering. I wasn't wondering about weighting magnitudes.

That's a good question that I also would be interested in the answer of. With no other obvious ordering, I think that it looks nice when it is alphabetical. (I don't know if Hugo just does that if we have equal weights?)

We have different types of documentation in our information architecture. Do they have ordering?
Perhaps concept -> task -> reference?

Looks as if the sections are ordered alphabetically with the current weighting, so I suppose we can just keep it as-is.

osg-grafana · 2022-01-28T10:16:00Z

docs/sources/configuration/config-param-lifecycle.md

+In order to simplify Mimir configuration, parameters are bucketed into 3 categories according to
+their maturity and intended use: _basic_, _advanced_, and _experimental_.
+
+## Basic


@GrafanaWriter, please weigh in here wrt "basic".

Could we avoid using the term "basic" as it can have editorial tones - similar to terms such as "simple" or "easy".

My suggestion - could we use "core"?

I think "core" is good.

"core" sounds good to me.
I've also seen us use the word 'stable', but that's more in contrast to 'experimental' flags.

So our hierarchy is that a flag is either 'stable' or 'experimental'
Independently, a flag is either 'core' or 'advanced'.
An 'advanced' flag can be 'stable' or 'experimental'.
An 'core' flag should never be 'experimental' I think?
I'm trying to build a venn diagram of this in my head.

An 'core' flag should never be 'experimental' I think?

Agree. A core parameter should never be experimental at the same time.

Wait @pracucci -- is that a typo in your response? it seems like you're saying the opposite...

Sorry, it was a typo. I forget a "never", which reverse the sense of the sentence. I updated the message above.

pracucci

Thanks @aknuds1 for working on this! I left few comments.

docs/sources/configuration/config-param-lifecycle.template

docs/sources/configuration/config-param-lifecycle.md

docs/sources/configuration/config-param-lifecycle.template

docs/sources/configuration/config-param-lifecycle.md

aknuds1 · 2022-01-28T13:52:57Z

@pracucci OK, will remove template.

pracucci

LGTM! We need a tech writer now.

RichiH · 2022-01-31T10:10:46Z

Breaking #938 (comment) out into its own top-level discussion:

Basic, advanced, and experimental overload two orthogonal dimensions into one:

"How advanced does the user need to be to use/configure this"
"How stable is the feature"

If we're talking user progression, basic, advanced, and expert are the common terms. Though I agree that basic can have negative connotations, in the context of "this is a basic setup" it makes more sense than "this is a core setup".

On stability, stable and experimental are the common terms.

One could argue that two categorizations are too complex for what we need, which would lead us to basic, advanced, expert, and experimental.

All that being said, while I believe that basic is more correct than core, I do not feel very strongly.

What I do feel strongly about is that whatever system we end up using here need to match what Grafana, Loki, and Tempo are using or will be using.

RichiH · 2022-01-31T11:51:28Z

PS: We would use "basic" in direct relation to "advanced" and "expert" not completely detached, so there is context for the reader.

aknuds1 · 2022-01-31T13:46:18Z

As a point of reference, VLC uses the "advanced" term for normally hidden parameters.

osg-grafana

Unblocking, and can rework this later as needed.

Signed-off-by: Arve Knudsen <[email protected]>

Co-authored-by: Marco Pracucci <[email protected]>

Signed-off-by: Arve Knudsen <[email protected]>

aknuds1 · 2022-02-04T09:12:45Z

After having discussed with @pracucci and @jdbaldry I'm going to merge this PR, although the question whether to rename the "basic" category to "core" isn't resolved yet. Renaming the category will in any case require renaming it also in the Mimir and GEM code bases (i.e., it goes beyond mere documentation), so we will make a dedicated issue regarding making that decision before launch.

aknuds1 marked this pull request as draft January 28, 2022 09:53

aknuds1 requested review from jdbaldry and osg-grafana January 28, 2022 09:53

aknuds1 added the type/docs Improvements or additions to documentation label Jan 28, 2022

aknuds1 commented Jan 28, 2022

View reviewed changes

osg-grafana requested a review from KMiller-Grafana January 28, 2022 10:14

osg-grafana reviewed Jan 28, 2022

View reviewed changes

pracucci reviewed Jan 28, 2022

View reviewed changes

aknuds1 force-pushed the chore/document-config-param-lifecycle branch from 450287f to 7fe5650 Compare January 28, 2022 13:05

aknuds1 requested a review from pracucci January 28, 2022 13:06

aknuds1 force-pushed the chore/document-config-param-lifecycle branch from 7fe5650 to 52b8845 Compare January 28, 2022 13:07

pracucci mentioned this pull request Jan 28, 2022

compactor: Tag advanced config parameters #947

Merged

1 task

pracucci reviewed Jan 28, 2022

View reviewed changes

docs/sources/configuration/config-param-lifecycle.template Outdated Show resolved Hide resolved

docs/sources/configuration/config-param-lifecycle.md Outdated Show resolved Hide resolved

docs/sources/configuration/config-param-lifecycle.md Outdated Show resolved Hide resolved

aknuds1 force-pushed the chore/document-config-param-lifecycle branch from 52b8845 to 94f4e15 Compare January 28, 2022 14:16

aknuds1 requested a review from pracucci January 28, 2022 14:17

pracucci reviewed Jan 28, 2022

View reviewed changes

jdbaldry mentioned this pull request Jan 31, 2022

Docs: Refactor existing documentation #966

Closed

jdbaldry mentioned this pull request Jan 31, 2022

Docs: Re-order, revise, review, and refactor Mimir documentation #732

Closed

53 tasks

osg-grafana approved these changes Feb 1, 2022

View reviewed changes

09jvilla mentioned this pull request Feb 1, 2022

Define criteria for categorizing configuration parameters #910

Closed

aknuds1 force-pushed the chore/document-config-param-lifecycle branch from 59c47d9 to 680f1a7 Compare February 3, 2022 13:13

aknuds1 and others added 5 commits February 3, 2022 15:08

docs: Add section on configuration parameter lifecycle

4f7689d

Signed-off-by: Arve Knudsen <[email protected]>

Update docs/sources/configuration/config-param-lifecycle.md

e1ca083

Co-authored-by: Marco Pracucci <[email protected]>

Tweak configuration parameter lifecycle doc

962fa7a

Signed-off-by: Arve Knudsen <[email protected]>

Remove config param lifecycle template

dc4408a

Signed-off-by: Arve Knudsen <[email protected]>

Tweak configuration parameter lifecycle doc

4b4a575

Signed-off-by: Arve Knudsen <[email protected]>

aknuds1 force-pushed the chore/document-config-param-lifecycle branch from 680f1a7 to 4b4a575 Compare February 3, 2022 14:08

aknuds1 assigned aknuds1 and unassigned aknuds1 Feb 4, 2022

aknuds1 changed the title ~~WIP: Docs: Add section on configuration parameter lifecycle~~ Docs: Add section on configuration parameter lifecycle Feb 4, 2022

aknuds1 marked this pull request as ready for review February 4, 2022 08:59

aknuds1 changed the title ~~Docs: Add section on configuration parameter lifecycle~~ Docs: Add section on configuration parameter categories Feb 4, 2022

aknuds1 merged commit 64a1235 into main Feb 4, 2022

aknuds1 deleted the chore/document-config-param-lifecycle branch February 4, 2022 09:13

jdbaldry mentioned this pull request Feb 4, 2022

Docs: Decide what to replace basic with in the configuration parameter categories #1034

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Docs: Add section on configuration parameter categories #938

Docs: Add section on configuration parameter categories #938

aknuds1 commented Jan 28, 2022 •

edited

Loading

aknuds1 Jan 28, 2022

GrafanaWriter Jan 28, 2022

aknuds1 Jan 31, 2022 •

edited

Loading

jdbaldry Jan 31, 2022

aknuds1 Feb 4, 2022

osg-grafana Jan 28, 2022

GrafanaWriter Jan 28, 2022

pracucci Jan 31, 2022

09jvilla Jan 31, 2022

pracucci Jan 31, 2022 •

edited

Loading

09jvilla Jan 31, 2022 •

edited

Loading

pracucci Feb 1, 2022

pracucci left a comment

aknuds1 commented Jan 28, 2022

pracucci left a comment

RichiH commented Jan 31, 2022 •

edited

Loading

RichiH commented Jan 31, 2022

aknuds1 commented Jan 31, 2022

osg-grafana left a comment

aknuds1 commented Feb 4, 2022 •

edited

Loading

Docs: Add section on configuration parameter categories #938

Docs: Add section on configuration parameter categories #938

Conversation

aknuds1 commented Jan 28, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aknuds1 Jan 31, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pracucci Jan 31, 2022 • edited Loading

Choose a reason for hiding this comment

09jvilla Jan 31, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

pracucci left a comment

Choose a reason for hiding this comment

aknuds1 commented Jan 28, 2022

pracucci left a comment

Choose a reason for hiding this comment

RichiH commented Jan 31, 2022 • edited Loading

RichiH commented Jan 31, 2022

aknuds1 commented Jan 31, 2022

osg-grafana left a comment

Choose a reason for hiding this comment

aknuds1 commented Feb 4, 2022 • edited Loading

aknuds1 commented Jan 28, 2022 •

edited

Loading

aknuds1 Jan 31, 2022 •

edited

Loading

pracucci Jan 31, 2022 •

edited

Loading

09jvilla Jan 31, 2022 •

edited

Loading

RichiH commented Jan 31, 2022 •

edited

Loading

aknuds1 commented Feb 4, 2022 •

edited

Loading