Clean up external links in procedure to manage hosts using Cockpit #3382
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: |
asteflova
added
Needs tech review
|
@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
pr-processor
bot
added
Needs re-review
and removed
Waiting on contributor
| [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.
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.
I propose to move these steps to a procedure to which we can link.
There was a problem hiding this comment.
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.
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.
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.
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.
Yes, I like this much better.
| ** 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.
| * 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.
| 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?
maximiliankolb
added
style review done
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: