Che server parameters reference documentation

[themr0c]

Is your task related to a problem? Please describe.

The discussion started with #19604, trying to sum up all difficulties we have with the che.properties documentation.

• For a user looking for Che server parameters documentation, the primary source of information is the documentation website.
• As we are running on Kubernetes, no user is editing the che.properties file.
• It's good to keep the documentation close to the code, but that doesn't mean it is mandatory to keep it inside the che.properties file.
• Authoring documentation directly in AsciiDoc would be easier than AsciiDoc embedded in comments. Same to validate the language.
• Pattern based substitutions on a single file don't work. Chunking the content would help define the context where pattern-based substitutions would work.
• The current display in tables is ugly.

Describe the solution you'd like

• Document each parameter in che.properties as an AsciiDoc reference file.

Example: ref_che-database.adoc

[id="ref_che-database_{context}"]
= `che.database`

Folder where Che stores internal data objects.

.Default value
====
----
${che.home}/storage
----
====

• Determine in which directory store these AsciiDoc files: same as che.properties?

• Put a pointer to the file in che.properties before each parameter.

• Modify the PR check to validate each parameter has a corresponding reference file

• Build the documentation using these AsciiDoc files. Run substitutions for terms that need context-based substitutions (Kubernetes, Che, namespace).

• This enables flexibility in the way we display documentation: for example, distinguish common parameters and parameters for advanced usage.

• If we need to use variables (prod-short, orch-name etc.), add a copy or a pointer to the antora-playbook.yml file in che-docs repository where they are defined.

• Then, the comments in che.properties may include additional information for developers, that don't need to go in the user facing docs.

Describe alternatives you've considered

• Add AsciiDoc variables into che.properties. Not desirable. See Language review on che.properties targeted at attributes occurences #19604
• Stop single-sourcing documentation of che.properties parameter. High risk to get documentation lagging behind.

[sparkoo]

idea: There are lot of properties. Would make sense to allow to logically group them together?

example: https://github.com/eclipse/che/blob/master/assembly/assembly-wsmaster-war/src/main/webapp/WEB-INF/classes/che/che.properties#L111 workspace sidecar cpu and memory limits/requests. Very similar properties and imho it would make sense to have them in one file.

[themr0c]

It is possible, but it will be easier to validate the files if their structure is predictable, atomic, always one parameter per file.

assembly files are the right tool to do these aggregations. They could exist in this repository or only in che-docs.

[themr0c]

NB: we have 194 parameters.

[themr0c]

The files would be like: https://github.com/eclipse/che/pull/19637/files

[themr0c]

Che Community meeting:

• Confirmation that current state is not satisfactory: Tables are poorly readable. Properties files are easier to scan to find information.
• In the current published documentation, it is not convenient to look at parameters in 2 places. For the user, it's not clear where to search. https://www.eclipse.org/che/docs/che-7/installation-guide/configuring-the-che-installation/ or https://www.eclipse.org/che/docs/che-7/installation-guide/advanced-configuration-options-for-the-che-server-component/ The criteria "why is it landing on this page" is not clear.
• Working with modular files will help to structure the aggregation of parameters in the reference page, and enable the reuse of topics in stories.
• Writing comments in the properties file is easier for developers. Reaction of platform team about this change?

[ibuziuk]

providing extra adoc file per property to the codebase and referencing them from the .propoerty files in order to fix the documentation website layout is a really controversial proposal. I personally -1. This proposal will make the property files much less readable, and less straightforward to maintain. In general, never have I seen such a design with extra adoc files per property in any of the upstream projects, and do prefer to have consolidated content in a single file.

[themr0c]

Let's find a less controversial path then.
A new proposal will be less automation, for a better doc.

Properties files are not the unique source of truth

I understand from the various discussions that building a reference documentation solely from the properties files is a dead end.

The properties file define:

• Name of the parameter
• Description.

The parameter is then used in 2 possible workflows:

• Configuration using the Operator
• Configuration using Helm

Each of these workflows determines:

• The default value
• The proper way to configure the value for the parameter.

For the Operator we even have 2 possibilities:

• A field in the CR (what is now in https://www.eclipse.org/che/docs/che-7/installation-guide/configuring-the-che-installation/ )
• Configuration via spec.server.customCheProperties

So we can use the properties file to write a draft for che-docs, but then we need to collect informations from other places to have a complete information.

Plan is to have this new process:

• Script assistance: determines if all the parameters in the properties files have their AsciiDoc reference file counterpart in che-docs
• Script assistance: for each new parameter, create a draft for a new corresponding AsciiDoc reference file.
• Humans: review and complete the draft.
• Humans: assess the position of the parameter in the outline.
• As writers are reviewers on the properties files, a review on these files triggers evaluation of necessary changes in che-docs.

I'll close the PR still open to work in that direction.

[yhontyk]

https://issues.redhat.com/browse/RHDEVDOCS-2968

[che-bot]

Issues go stale after 180 days of inactivity. lifecycle/stale issues rot after an additional 7 days of inactivity and eventually close.

Mark the issue as fresh with /remove-lifecycle stale in a new comment.

If this issue is safe to close now please do so.

Moderators: Add lifecycle/frozen label to avoid stale mode.