One AsciiDoc reference file per parameter

[themr0c]

To feed the discussion in #19630

Now:

• The location of the files is maybe not optimal.
• This PR doesn't include changes to validate changes on che.properties or multiuser.properties.
• Added the script that generated the ref files for reference.
• Added an assembly file, which is not exactly following what we have in che-docs. Ordering need some work.

[che-bot]

Can one of the admins verify this patch?

[themr0c]

How it would look like in the docs website:

[skabashnyuk]

Please merge the latest master to fix the build check.

[sparkoo]

default values in adoc files are prone to become obsolete, this is not safe. It's arguable if these default values are really default, because che-operator/helm might set them to something different with their default installation configuration.

[sparkoo]

how are adoc files going to be referenced from che/multiuser.properties ? Is it in the scope of this PR ?

[sparkoo]

why is there a script in this PR? My assumption was that the comments would be transferred in one batch, so why we need the script here? What will be the process.

[themr0c]

default values in adoc files are prone to become obsolete, this is not safe. It's arguable if these default values are really default, because che-operator/helm might set them to something different with their default installation configuration.

• A change of the defaults in a properties file must be reflected in the documentation. This is the kind of thing we can catch at review time, if we don't manage to set up a scripted check.

• Default values (for documentation) are taken from the current content in the properties files. As it is in current docs. If we have to document 3 defaults: default, default for che-operator, default for helm, would it make sense to document here the defaults for the operator and for helm? That would build the case for the documentation entirely in che-docs.

[themr0c]

why is there a script in this PR? My assumption was that the comments would be transferred in one batch, so why we need the script here? What will be the process.

Because it's a draft and I fear the content will get obsolete before we reach consensus. Need to remove it before finalizing.

[themr0c]

how are adoc files going to be referenced from che/multiuser.properties ? Is it in the scope of this PR ?

I believe we should do it in 2 different PR, change the comments once the documentation has done the transition.

I believe we could replace comments by:

# See: path/to/file.adoc

[themr0c]

• Is the path proposed here something that make sense? Any better / more reasonable idea?

[themr0c]

• New check for PR validation is missing, script here can maybe serve as a starting point.

[themr0c]

Closing, new plan described here: #19630 (comment)