Mini Content Journey

Who is your target persona?

Satellite user running remote jobs (admin-type role)

What stage of the user journey are you targeting?

Learn, Try, Expand

Why is this content important?

This area was highlighted by Satellite CS as a good one to focus on.

What is the main user goal aka job to be done?

As a Satellite admin-type user, I want to perform various tasks on multiple Satellite hosts simultaneously.

What high level steps does the user need to take to accomplish the goal?

1. Learn about REX and the push/pull modes, 2. Decide which mode to use, 3. Run basic jobs, 4. Tweak the settings and run more advanced jobs.

(Optional) What is the general sentiment of users towards this goal?

(Optional) What pain points are the user likely to encounter when accomplishing this goal?

Users are likely to appreciate examples and tutorial-like example REX jobs.

(Optional) What other feedback do users have around this goal?

(Optional) Are there any additional opportunities you can also implement for the user when documenting this goal?

Existing docs for REX don't comply with Red Hat's documentation standards.

• Inconsistent terminology:
  • Remote execution/remote jobs/remote execution of commands on hosts
  • Pull client/mqtt pull client/pull mode/mqtt mode + ssh mode/push mode
• Lack of examples and hands-on procedures, tutorials
• Conceptual/procedural/referential information is not clearly separated
• Too many modules, several very small procedures about configuring a single option
• Procedures don't follow DITA requirements.

Proposed solution:

• Rearrange information based on the information type: strictly separate concept, procedures, and reference.
• Investigate ways to turn some procedures (based on setting a single option) into a reference module (with an overview of options).
• Reduce the amount of content (lines) that we maintain.
• Define and use consistent terminology.
• Make all new content follow modular docs/DITA requirements (to the best of our current knowledge)
• Add examples.

Right now, we effectively have two documents that describe REX: See "Links to existing content". If we manage to merge them, we could then create a new guide specifically for "Managing Satellite hosts remotely".

Links to existing content 

Configuring and setting up remote jobs

Configuring hosts by using Ansible also covers remote execution and we should consider whether we really need two resources for REX as a feature.

People:

• SME: [SME name]
• QE: [QE name]

Release Note: No

Documentation Outline

• Concept:
  • Overview (what REX is and why it's useful)
  • Architecture (the technical solution underlying REX)
  • Comparison of the two REX modes and the features they support (Ansible vs Script providers)

• Procedure:
  • Configuring hosts for REX
  • Permissions (defining which roles can trigger which jobs)
  • Establishing a connection for SSH-mode REX jobs (SSH keys, Kerberos TGTs)
  • Defining jobs templates
  • Running the actual jobs

• Reference:
  • Highlighted advanced options and their use cases
  • Highlighted REX templates (there are over 100 templates, we won't document them all but can share examples worth highlighting)
• Any existing procedure that is missing a reference to a related REX template that is worth highlighting
  • See https://docs.theforeman.org/nightly/Upgrading_Project/index-katello.html#upgrading_smart-proxy_server_upgrading-connected – the NOTE that mentions a REX template related to the procedure