Recommendations:

• Review links and xrefs throughout the document and remove unnecessary occurrences. The "Adding network interfaces" procedures are very old and have not been reviewed recently. The same recommendation applies to "Additional resources".
• Review procedures to ensure the following:
  • Compliance with our minimalism guidelines. This includes removing self-evident steps and options and using bullet lists or subprocedures to improve usability.
  • Little or no concept information in actual steps. If a step requires a link or explanation, it is usually preferable to move the information to the introduction or to a separate concept module to ensure that the user has all the information they need before they start the procedure.
  • Compliance with our current UI documentation guidelines.

Updates:

• Review sections for duplication. A lot of content in "Administering hosts" overlaps with "Provisioning hosts" and "Administering Satellite".
• Links to RHEL docs need to be updated. Old links resolve to the RHEL splash page instead of a 404, which means they are not easy to spot. Links to the "standard install" guide need to be checked because RHEL now has 4 installation guides.
• Spike and separate epic: Reorganize Managing hosts (separate from improvements)
  • Move admin procedures to admin guide (can link in the Prerequisites). Managing hosts is primarily for users, not admins. Examples: Enabling RHEL console, syncing templates.
  • Consider moving REX to a separate guide because it is large and fairly self-contained. Reorganize REX guide by push/pull modes and expand description of use cases.
  • Improve use case descriptions. Currently, Administering hosts is a collection of unrelated procedures that describe everything a user can do on the "All hosts" page. This needs to be organized into coherent use cases.

Source: Red Hat Satellite Documentation Improvement Opportunities

Users want to avoid jumping between two docs while configuring a feature or trying to use a feature. Everything should be straightforward and mentioned in the same doc section. We understand that repetition of instructions is usually avoided and hence we provide hyperlinks of the applicable doc chapter\section, but perhaps our end-users are less concerned about that.

A good example would be Upgrade and Installation guides which are easy to follow

A rather not-so-good example would be the “Managing Hosts” guide, where almost every single section has different hyperlinks to other docs. (look at chapter 5)

Goals: Improve usability by making procedures more compact.

Replace links with real steps. Example: Adding a virtual interface

Specify the general interface settings. The applicable configuration options are the same as for the physical interfaces described in Section 5.1, “Adding a physical interface”.

This is not a good user experience. We write modules so that they can be reused. The physical interface module should be reused with conditional text for other types of interfaces.

I recommend moving "For more information" links out of procedure steps to abstracts or introductions. It is better for the user to review relevant information before starting a procedure. Example:

• Bond options: Specify a space-separated list of configuration options, for example miimon=100. For more information on configuration options for bonded interfaces, see Configuring network bonding in the Red Hat Enterprise Linux Configuring and Managing Networking guide.