[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
[che-dev] Improve Che server parameters reference documentation
|
Hello,
We have been thinking of this to improve the Che server parameters
reference documentation. As it's an big (and uncommon) change, the
discussion is open.
https://github.com/eclipse/che/issues/19630
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.
Describe alternatives you've considered
Add AsciiDoc variables into che.properties. Not desirable. See
#19604
Stop single-sourcing documentation of che.properties parameter.
High risk to get documentation lagging behind.
--
Fabrice Flore-Thébault
He/Him/His
Technical Writer @ Red Hat
