Bug 846687 - Confusing and inconsistent references to "up2date" and other registration/updating tools
Confusing and inconsistent references to "up2date" and other registration/upd...
Status: CLOSED NEXTRELEASE
Product: Red Hat Satellite 5
Classification: Red Hat
Component: Docs Reference Guide (Show other bugs)
560
Unspecified Unspecified
unspecified Severity unspecified
: ---
: ---
Assigned To: Athene Chan
Dan Macpherson
:
Depends On:
Blocks: sat55-docs 922607
  Show dependency treegraph
 
Reported: 2012-08-08 08:47 EDT by Tim Jackson
Modified: 2015-05-11 18:08 EDT (History)
4 users (show)

See Also:
Fixed In Version:
Doc Type: Bug Fix
Doc Text:
Story Points: ---
Clone Of:
Environment:
Last Closed: 2013-07-08 18:44:06 EDT
Type: Bug
Regression: ---
Mount Type: ---
Documentation: ---
CRM:
Verified Versions:
Category: ---
oVirt Team: ---
RHEL 7.3 requirements from Atomic Host:
Cloudforms Team: ---


Attachments (Terms of Use)

  None (edit)
Description Tim Jackson 2012-08-08 08:47:52 EDT
Description of problem:
There are numerous references to "up2date" in the Reference Guide. Whilst these are not necessarily wrong, given that RHEL3 and RHEL4 have ended their Production 3 phases, the following should be considered:

Consideration 1) The prominence of references to "up2date" is very high given that the up2date command line tool is a legacy tool, beginning with it being described as the first component of RHN, in bold, on page 1 of chapter 1. This is partly caused by using "up2date" as a synonym for the whole set of client tools, which vary between RHEL versions.

Consideration 2) A number of references read something like this: "To do ABC, you use up2date...[continues for several lines/paragraphs]...oh and if you are using RHEL5 you do XYZ instead". (example: chapter 1.8). For an end user, reading something like is awkward/confusing at best. Better to say something like:
"The following instructions vary depending on the version of RHEL.
 - For RHEL X: Do this.
 - For RHEL Y: do other thing".

Consideration 3) Building on (b), all references to up2date should have clear alternative references for RHEL5+ systems which use "yum" instead of "up2date". This is not always the case.

Consideration 4) all references should be qualified by making it clear that "up2date" is only applicable for systems <=RHEL4. This might seem a bit boring, but if people read only one chapter or section, then by not making the reference clear it is confusing.

The problems can be easily seen by searching through the document for "up2date" and checking whether any of the above apply. Some examples are below.

I initially found this problem whilst trying to provide specific references to the documentation to a customer using RHEL6 and it was quite confusing. Now, it's a fact that the mixture of update methods and associated tools/filenames on RHEL3-6 *is* somewhat complicated/confusing, but that's why it would be great if the documentation could help to cast some clear light on this.


SUGGESTIONS/RECOMMENDATIONS:
1. Early in the document, briefly explain to the reader the history of RHN and the associated tools

2. Choose clear and separate naming for "the tools and method that are used to register and retrieve updates from Satellite" from "the 'up2date' command line tool" and use the naming consistently. Personally, I would suggest the following:

"up2date": The command line tool up2date, which is used on RHEL <=4 only.

"Red Hat Update Agent": Discontinue using this terminology in the documentation, in favour of one of: "up2date", "rhn_register", "yum", "the RHN plugin for yum", "Red Hat Network Client Tools", or "pup", depending on what is meant.

"Red Hat Network Registration Client": rhn_register, or up2date in registration mode (--register)

"Red Hat Network Client Tools": programs and libraries to allow a system to receive software updates from Red Hat Network. (a generic term which can be used for all RHEL versions)


3. Divide the tools and files to be documented into two categories:
a) applicable to all RHEL versions (e.g. rhnreg_ks, /etc/sysconfig/rhn/up2date)
b) applicable only to RHEL3/4
Make a prominent reference table that clearly shows this, and briefly explain why "up2date" is still referenced in some filenames even on RHEL5 and RHEL6.
Break up the document into separate sections according to these categories, for example: Server, Client for RHEL3/4, Client for RHEL5, Client for RHEL6.

EXAMPLES

1) Chapter 1, page 1: (example of Consideration 1)
a) lists the main components of RHN, but mentions up2date as the most prominent one, twice in bold on the first page.
b) "The Red Hat Update Agent (up2date) provides your initial connection to Red Hat Network".

2) section 1.7: (example of Consideration 2)
"...you _must_ obtain the Red Hat Update Agent (up2date)" (emphasis mine)

3) Chapter 1, table 1.1:  (example of Consideration 3)
lists up2date and up2date-gnome without qualification or RHEL5+ alternatives. Packages called "rhn_register" and "rhn_register-gnome" are referenced, which don't exist on RHEL6.

4) Chapter 4: if you read from the start, this chapter claims to be entirely RHEL4 focused, as it discusses the RHEL4-based Red Hat Update Agent. (First line: "The Red Hat Update Agent is your connection to Red Hat Network on Red Hat Enterprise Linux 4"). However, in section 4.3.3, it suddenly mentions RHEL5, leaving the reader confused. Furthermore, a significant amount of the information contained in Chapter 4 (especially section 4.5 onwards e.g. registering with rhnreg_ks) is in fact generally applicable, and is referenced from other sections that are not RHEL4 specific (e.g. section 7.2). Very confusing!
Comment 1 Clifford Perry 2012-08-09 10:28:18 EDT
We have for the 5.5 docs/release been trying to clean some of this up. Going to assign to docs folks for review of input. 

Cliff
Comment 2 Lana Brindley 2012-08-15 23:50:54 EDT
This will be addressed for v.next.

LKB

Note You need to log in before you can comment on or make changes to this bug.