-
Notifications
You must be signed in to change notification settings - Fork 946
ARTEMIS-5850 consolidate web console docs #6182
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
brusdev
left a comment
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Great improvement of the web console doc. It is very detailed now!
I suggested optional changes to replace the plugin word with view.
| The rest of this document will feature on these two tabs. | ||
| The rest of this document will focus on these two views. | ||
|
|
||
| This menu can be disabled or enabled using the `☰` icon in the very top left. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| This menu can be disabled or enabled using the `☰` icon in the very top left. | |
| Use the `☰` icon in the top left to show or hide this menu. |
| Click kbd:[Artemis] in the left navigation bar to see the broker-specific plugin. | ||
| The Artemis view shows data in a tabular format. | ||
| (The Artemis view won't appear if there is no broker in this JVM). |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| Click kbd:[Artemis] in the left navigation bar to see the broker-specific plugin. | |
| The Artemis view shows data in a tabular format. | |
| (The Artemis view won't appear if there is no broker in this JVM). | |
| Click the kbd:[Artemis] item in the left navigation bar to open the Artemis view. | |
| (The Artemis item is not present if there is no broker in this JVM). |
| (The Artemis view won't appear if there is no broker in this JVM). | ||
|
|
||
| === Status Tab | ||
| The following functionality is available on every tab that shows tabulated data: |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| The following functionality is available on every tab that shows tabulated data: | |
| The following functionality is available on every data table: |
| Click kbd:[Artemis JMX] in the left navigation bar to see the Artemis JMX specific plugin. | ||
| (The Artemis JMX tab won't appear if there is no broker in this JVM). | ||
| The Artemis JMX plugin works very much the same as the normal JMX plugin, however with a focus on interacting with an Artemis broker. |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
| Click kbd:[Artemis JMX] in the left navigation bar to see the Artemis JMX specific plugin. | |
| (The Artemis JMX tab won't appear if there is no broker in this JVM). | |
| The Artemis JMX plugin works very much the same as the normal JMX plugin, however with a focus on interacting with an Artemis broker. | |
| Click the kbd:[Artemis JMX] item in the left navigation bar to see the Artemis JMX view. | |
| (The Artemis JMX item is not present if there is no broker in this JVM). | |
| The Artemis JMX view is similar to the standard JMX view, however with a focus on interacting with an Artemis broker. |
|
Not entirely sure about this consolidation direction as opposed to for example the reverse. The reason the new consoles docs were prepared outwith the Artemis build is that it can be used separately and it is released/updated separately, so it made sense that its docs should be able to be updated separately with its release as well. Arguably the broker docs that this change is overhauling should have been minimised further at that point and referenced out to the console docs (which would ideally also have been version-specific to facilitate that better, and perhaps in the console tree to be updated as changes are made to the console). Going this way, any time we make significant changes in a console release that should really be documented we then either have to just leave the console docs stale when releasing, or duplicate [some part of] this content back there to do it, since we couldnt update these docs on the site until after the next Artemis release (even if we did it manually out of band on the site, since they would then be incorrect for the current released Artemis version). For admittedly unusual reasons its taken us over 2 months since 1.4.0 was released, and in the end we skipped it for embedding with the broker, but will still be over a week between 1.5.0 and 2.50.0 going out. |
|
@gemmellr, all good points. Ultimately the web console needs docs like the broker has - AsciiDoc files in the console repo. Markdown is great for a lot of things, but technical docs like this is not one of them. That's the main reason I consolidated into the broker. I'll adopt Dom's suggestions and begin work on a console PR that gets us where we need to be. |
Currently documentation for the web console is in 2 places:
Each set of documentation has information that the other set doesn't as well as significant overlap. This documentation should be consolidated with a preference for the AsciiDoc format since it's superior to Markdown in this context.
Also, the docs needs to be updated to account for new functionality and behavior introduced in recent versions.
Once this is merged I will change the docs at https://github.com/apache/artemis-website/tree/main/src/components/artemis-console/documentation to only include the bits which are relevant for standalone use and then point to these new docs for reference.