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.

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.