-
Notifications
You must be signed in to change notification settings - Fork 95
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
Clean up external links in procedure to manage hosts using Cockpit #3382
base: master
Are you sure you want to change the base?
Conversation
The PR preview for 7bc6714 is available at theforeman-foreman-documentation-preview-pr-3382.surge.sh The following output files are affected by this PR: |
@adamruzicka Can you please take a look to make sure the rest of the section looks okay? |
guides/common/modules/proc_managing-and-monitoring-hosts-using-cockpit.adoc
Show resolved
Hide resolved
guides/common/modules/proc_managing-and-monitoring-hosts-using-cockpit.adoc
Outdated
Show resolved
Hide resolved
We don't want users to think that they need to do any of the installation etc. steps described in the linked docs
[NOTE] | ||
==== | ||
You can use a job template to install {the-Cockpit}. | ||
To view the template in {ProjectWebUI}, navigate to *Monitor* > *Jobs* and click *Run Job*. | ||
From the *Job category* list, select *Ansible Services*. | ||
From the *Job template* list, select *Service Action {endash} Enable Web Console*. | ||
==== |
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.
I think this might be too much for a prerequisite but then again, I can't think of a better way to point users to the template. Does anyone have suggestions?
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.
I propose to move these steps to a procedure to which we can link.
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.
I'm not trying to describe a procedure, just the place where users can find the template. Do you have an alternative solution? What I'm trying to do is let users know that this template exists. I can't think of a way to do that without guiding them through the web UI.
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 procedure itself would be 13. Configuring and setting up remote jobs. But how to best point to the particular template to use?
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.
I see this as a new 9.2 "Enabling Cockput on hosts": https://docs.theforeman.org/nightly/Managing_Hosts/index-katello.html#host-management-and-monitoring-by-using-cockpit or similar.
The procedure itself does not need to duplicate all steps for REX jobs, but reference a procedure and mention the correct job category+job template.
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.
I don't know, I'd still like to avoid adding a whole new procedure. I wouldn't want to set a precedent for creating a whole new module every time I'd like to reference a job template/ansible module/etc. I still hope there is a simpler way to achieve that, one that doesn't eventually contribute to doc bloat :)
How about now? Just a note that the template is there and which category it's included in?
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.
Yes, I like this much better.
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.
Two minor optional suggestions. Overall LGTM
** For {RHEL}{nbsp}8, see {RHELDocsBaseURL}8/html/managing_systems_using_the_rhel_8_web_console/getting-started-with-the-rhel-8-web-console_system-management-using-the-rhel-8-web-console#installing-the-web-console_getting-started-with-the-rhel-8-web-console[Installing the web console] in _Managing systems using the RHEL{nbsp}8 web console_. | ||
** For {RHEL}{nbsp}7, see {RHELDocsBaseURL}7/html/managing_systems_using_the_rhel_7_web_console/getting-started-with-the-rhel-web-console_system-management-using-the-rhel-7-web-console#installing-the-web-console_getting-started-with-the-web-console[Installing the web console] in _Managing systems using the RHEL{nbsp}7 web console_. | ||
endif::[] | ||
* You have installed {the-Cockpit} on the host that you want to view. |
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.
* You have installed {the-Cockpit} on the host that you want to view. | |
* You have installed {the-Cockpit} on the host that you want to manage and monitor. |
"view" is probably not doing Web Console any justice. I've copied the verbs from the heading. Does this make sense? Or maybe just "manage"? Or "interact with"?
* You have installed {the-Cockpit} on the host that you want to view. | ||
+ | ||
{Project} provides a job template named *Service Action {endash} Enable Web Console* under the *Ansible Services* job category that you can use to install {the-Cockpit}. | ||
For more information about using remote jobs, see xref:Configuring_and_Setting_Up_Remote_Jobs_{context}[]. |
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.
For more information about using remote jobs, see xref:Configuring_and_Setting_Up_Remote_Jobs_{context}[]. | |
For more information about running remote jobs, see xref:Configuring_and_Setting_Up_Remote_Jobs_{context}[]. |
Or "execute" like https://docs.theforeman.org/nightly/Managing_Hosts/index-katello.html#executing-a-remote-job_managing-hosts?
What changes are you introducing?
Why are you introducing these changes? (Explanation, links to references, issues, etc.)
https://issues.redhat.com/browse/SAT-28721 reported that a link to RHEL 9 was missing from the Prerequisites. @adamruzicka suggested to drop the links rather than update the list.
Anything else to add? (Considerations, potential downsides, alternative solutions you have explored, etc.)
N/A
Checklists
Please cherry-pick my commits into: