Mini Content Journey

Who is your target persona?

Administrator.

What stage of the user journey are you targeting?

Expand

Why is this content important?

Upgrade guide is one of the most frequently visited Satellite documents.

Suboptimal upgrade XP (which includes references to documentation XP) is mentioned for example in https://issues.redhat.com/browse/SAT-23415 

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

As a Satellite administrator, I want the Satellite upgrade guide to provide clear and concise information and well-defined steps, so that I can efficiently and confidently upgrade to the next version with minimal disruption to my environment.

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

1. Read Release notes
2. Follow upgrade documentation
3. Troubleshoot if I run into problems
4. Repeat if upgrading from an old version of Satellite

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

From https://issues.redhat.com/browse/SAT-23415:

• Upgrading is an intimidating experience, in large part due to the upgrade procedure requiring too many steps

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

From https://issues.redhat.com/browse/SAT-23415:

• "Steps for upgrading the satellite with external databases are not very clear"
• A broken upgrade attempt results in hours/days of troubleshooting

Skip-level upgrades:

• In environments running older versions of Satellite, customers need to go through multiple upgrades to bring their environment to one of the more current versions. As a result, they are hesitant to start upgrading at all. A smooth documentation experience can alleviate that hesitation.

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

Feedback from PX:

• The upgrade guide is "very generic": It covers all the possible upgrade scenarios and environments. It's difficult and time consuming to understand what steps a particular customer needs to follow in their scenario.
  • Possible solution A: Clearer structure that provides end-to-end instructions. Implement hints like "Optional:" and "If you are using an external database, do XYZ" to help users clearly recognize what does and does not apply to their environment.
  • Possible solution B: Provide one (shorter, simpler) procedure for "happy path" and another (more complex) for "detailed path"

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

Links to existing content 

• https://docs.redhat.com/en/documentation/red_hat_satellite/6.16/html-single/upgrading_connected_red_hat_satellite_to_6.16/index
• https://docs.redhat.com/en/documentation/red_hat_satellite/6.16/html-single/upgrading_disconnected_red_hat_satellite_to_6.16/index 

People:

• SME: Evgeni Golov
• QE: Lukáš Pramuk

Release Note: No

Documentation Outline (just an estimate, the final outline might be different)

• Upgrade path/Upgrade overview (concept)
  • Recently improved in https://github.com/theforeman/foreman-documentation/pull/3408 

• Planning the upgrade (assembly)
  • Upgrading Capsules separately from Satellite (concept)
  • Considerations: Existing content in the guide that does not fit into procedures or prerequisites. Information that is not actionable directly during the upgrade. (Concept)
  • Best practices (for example, following the progress of the upgrade) (Concept)
• Prerequisites
  • A series of concise and clear action items users must follow before the upgrade. Avoid lengthy explanations.

• Upgrading a connected server (Procedure)

• • Synchronizing repositories (Procedure)
  • Optional: Upgrading the external database (Procedure)
  • Optional: Upgrading the external database OS (Procedure)

• • Post-upgrade tasks (Procedure)
• Upgrading Capsule Servers
  • Sub-procedures similar to Upgrading a connected server