Replies: 3 comments 2 replies
-
|
Example of documentation for relational database setup: Some highlights:
Hostname is not relevant here really, it's just included to show that we can include exactly what options we would want to include on a page, which may sometimes be options that are not directly configuring what is covered by the guide, but may also have some relevance. |
Beta Was this translation helpful? Give feedback.
-
|
The DB guide is an example of a guide that we would want to include directly in the CLI, with something along the lines of: |
Beta Was this translation helpful? Give feedback.
-
|
Example of generated all-config page: Some highlights:
This serves more as an example of how we can generate an all-config page, and is not a proposal for how it should finally look like as it does need a fair bit of polish to be nice. |
Beta Was this translation helpful? Give feedback.
-
|
@stianst This is a big change so thanks for the update. It looks it will provide great integration with the CLI, making it easier for the user. Will we be meeting to discuss how this will affect single-sourcing to generate the product documentation? Also, we are just about complete in creating content that meets Red Hat standards, so want to be sure we stay on that path. |
Beta Was this translation helpful? Give feedback.
-
|
@DGuhr, @pedroigor, @stianst I have not done this before, but here's an idea to consider for creating documentation efficiently. I understand that limiting each line to one sentence has many advantages.
|
Beta Was this translation helpful? Give feedback.
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
-
The Quarkus distribution has significantly improved the UX around configuration, and is significantly simplifying tasks such as configuring the relational database. This has a big impact on the server installation and configuration guide, where very little of the content is still relevant for the Quarkus distribution.
In addition we want to be able to connect the CLI and the documentation together, and not have to manually update the two. This goes both ways where CLI options should be automatically populated into the documentation, but also the other way where we want to build man-pages from the documentation that is available directly in the CLI.
With this in mind we are creating a new set of documentation for the server, which will be added to the main repository, and utilise FreeMarker to connect it to the CLI options. This will also generate manpages that can be included in the CLI.
There will be a number of self-contained guides for topics such as config, database, hostname, proxy, etc. These guides will be hosted on keycloak.org as separate guides with an ability to lookup the guides similarly to what Quarkus is doing. For Keycloak we already have a starting point for this with the new getting started guides.
Beta Was this translation helpful? Give feedback.
All reactions