Ryan McCabe's response to the attached document:

On Thu, Oct 14, 2010 at 10:59:00PM +0200, Jan Pokorný wrote:
> >   - subitem 5
> >     * I would add:
> >       "(Note:) Missing packages are installed in either case
> >       (if you have sufficient subscriptions)."
> >       Ryan, agreed?

Yeah. Even if you select "use locally installed packages" if any of the
base cluster components are missing (cman, rgmanager, modcluster -- and
all their deps) they will be installed. If they cannot be installed, the
node creation will fail.


Ryan

In 'Heuristics' row of table 3.1:

TKO — The number of cycles a node must miss to be declared dead. The value of TKO is automatically determined if left blank in the Quorum Disk Configuration dialog box. 

... this should be rewritten to talk about the heuristic's availability, not the node. (The one talking about the quorumd tko is correct; that one is about node liveliness)

Jan raised some points

Maybe:

Path to Program — The program used to determine if this heuristic is available. This can be anything that can be executed by /bin/sh -c. A return value of 0 indicates success; anything else indicates failure. This field is required.

Interval — The frequency (in seconds) at which the heuristic is polled. The default interval for every heuristic is 2 seconds.

Score — The weight of this heuristic. Be careful when determining scores for heuristics. The default score for each heuristic is 1.

TKO — The number of consecutive failures required before this heuristic is declared unavailable. [The value of TKO is automatically determined if left blank[1]].




1. note that the auto-configuration of heuristic TKO feature will not be in the cluster software prior to 6.1.

For RHEL 6, I was able to incorporate the comments regarding sections 3.3, 3.4, and 3.6.1. I also updated the table of heuristic parameters as per Lon's suggestion, and I removed the note I had about automatically determined TKO value since it is not available in RHEL 6.

I will look at the other points in the review for the next release of the document.

Below, I am adding the remaining notes of my review of chapters 3 and 4.
It follows the same style I used in the mail that is attached
(attachment 453580 [details]). Some notes are rather subjetive.

o 3.7.1. Adding a Failover Domain: item 2
  - the Create a Failover Domain window
    -> the Create a Failover Domain dialog (see general notes below)

o 3.7.1. Adding a Failover Domain: Figure 3.7
  * maybe this was a purpose, but when I compare "live" version of
    this dialog with the screenshot used, I am missing top and left
    boarders (however good thing the dialog was cropped and not
    displayed with what has luci on background)

  - luci failover domain configuration page
    -> luci failover domain configuration dialog

o 3.9. Adding a Cluster Service to the Cluster: whole section
  * no need to have first letter upper-cased with "Global resource"
    (outside the references to other sections etc.)

o 3.9. Adding a Cluster Service to the Cluster: item 3
  - On the Add a Service window
    -> On the Add a service window
    * the trouble is that luci is not consistent in lower/upper casing
      of dialogs' titles, following bug was filed to address this:
      https://bugzilla.redhat.com/show_bug.cgi?id=643488

o 3.9. Adding a Cluster Service to the Cluster: items 2, 3
  - Add a service window
    -> Add a service dialog (see general notes below)
    
o 3.9. Adding a Cluster Service to the Cluster: item 8
  - Clicking Add a resource causes the display of a drop-down box that
    allows you (...)
    * to make clearer navigation (back)references hereafter, I would add
      concrete name of the dialog
    -> Clicking Add a resource causes the display of the Add a resource
       to this service drop-down box that allows you (...)

  * I do not know how much complexity this would add (when trying to
    obey the guidelines for documentation), but it could be logical
    to move items 9--11 as subitems of item 8

o 3.9. Adding a Cluster Service to the Cluster: item 10 -- note
  * I had to read the note more times to actually understand it,
    steps to make it clearer:
    * omit second occurence of "a Samba-service resource" -> "it"
    * "not to a resource within a service"
      -> "not as a child to/of another resource" (?)
    * usage of a/the correct?

o 4.2.1. Rebooting a Cluster Node: last note
  - It is also possible to reboot more than one node at a time by
    selecting all of the nodes to reboot before clicking on Reboot.
    * from general case (more than one node) it jumps directly
      to special case of it (all of the nodes)

o 4.3. Starting, Stopping, Restarting, and Deleting Clusters: end part
  - To delete a cluster entirely from the luci interface, perform
    the following steps
    * it is actually explained with the item 2, that this doesn't
      mean "deletion of cluster from the luci interface",
      but rather the "physical" termination of cluster's lifeline,
      which includes that such cluster is no longer displayed
      in the luci interface, but this could be more obvious
      beforehand
    * maybe a warning that the action of "deleting cluster"
      in this context is a destructive operation that cannot
      be undone (at least not easily if the original configuration
      of the cluster was quite comprehensive -- everything has to
      be recreated and redefined from the scratch to restore
      equivalent cluster)

o 4.4. Managing High-Availability Services: first list
  * trailing dot vs. no dot

o 4.4. Managing High-Availability Services: second list, more items
  * copy&paste mistake
    - (...) icon starts the service you have displayed.
    * "starts" should vary according to the context
  * to be honest, seeing visually identical paragraphs (and in closer
    look finding out its almost true) discourages me, as a reader,
    from trying to get new information (no offence, I found out
    that this task of documentation of something that looks easily
    when being done in GUI, is pretty tricky to describe in text)

o 4.4. Managing High-Availability Services: second list, 3rd item
  - currently running. select any services
    * dot instead of comma


o general notes
  - luci formatted with bold/without formatting inconsistency
    * IMHO this should be kept consistent

  - inconsistent usage of "dialog (box)"/"page"/"window"/"screen"
    * some cases mentioned already, especially "page" and "window"
      ones
    * I humbly suggest using "dialog" for elements that really looks
      and behaves like a dialog (i.e. standalone, usually modal part
      of the GUI displayed on the top of others that e.g. asks user to
      input something); using both page and screen for the whole pages
      seems OK to me (but the simplification could be applied, too)

  - in the comments to the mentioned bug
    https://bugzilla.redhat.com/show_bug.cgi?id=643488,
    you can find current lower/upper casing of dialogs' titles,
    which applies to luci on RHEL 6.0

I think it's worth pointing out luci (AFAIK not-yet standard) homepage http://sources.redhat.com/cluster/wiki/Luci, especially "Deployment" section, where I keep adding new remarks from time to time -- when I come to something useful to share.

(Before taking anything to official docs, a little discretion is still appropriate.)

Update to the status of this bug:

I have now incorporated a large percentage of these comments into my working draft of the RHEL 6 version of the cluster adminstration guide (and checked them into Conga).  This is what I have left to do before closing this bug:

- I inherited the capitalization scheme for "web" vs "Web" from previous versions of this document. I will check to be sure it remains according to department standards.

- I need to check the final wording of the step in section 3.2 about self-signed SSL certificate -- what I now have seems awkward, but at least it acknowledges browser-specific differences.

- I will look over all the figures I have to be sure they are the right size and emphasize what I want to emphasize. It was a conscious decision not to include the full screen for each illustration, so I can check into doing a better job of enlarging only what I intend to show (which I had already been trying to do).

- My understanding is that you do, indeed, need to configure fencing for each node or we do not support your configuration.

- I will follow up on Jan's comment about adding information about accessing remote luci clients through the firewall. I do not know what this refers to.

- I will do a general lookover of both Conga chapters to be sure that I refer to drop-down boxes by their specific name (rather than "the drop-down box").

- I turned items 9-11 of section 3.9 into subitems of item 8, but I need to verify how well that formats.

- I need to verify the technical accuracy of the rewritten note in section 3.9 about making sure a Samba-service is its own resource and not a child of another resource. That note was inherited from older versions of the tool so it needs verifying anyway.

- Check to be sure that the new caution I added about the destructive nature of deleting clusters formats correctly.

- Look at section 4.4 and see if there is a better way to structure this section so that it is not mostly the same information in every bullet.

- Look again to be sure that I use "dialog" and page and screen and window in the manner Jan suggests.

Check but 643488 for information on how luci capitalizes dialog titles.

Other than that I think I've made all the updates at this point in preparation for RHEL 6.1.

Just a heads up that bug #643488 is now on POST (you should be able to find everything necessary in the comment https://bugzilla.redhat.com/show_bug.cgi?id=643488#c5).  I've also added this bug to "See also".

I have reworked section 4.4 so it does not repeat blocks of information.

I have checked the formatting of all of the reworked sections.

I will add a note about documenting access to remote luci clients through the firewall to BZ617634, which is a related bug about setting up luci communication and is a 6.2 bug now.

The rest of the issues in this bug are part of BZ#665055, which is the general update the Conga doc for the 6.1 display bug. So I'm now marking this bug as a duplicate of that bug to keep the open issues together in one place.

*** This bug has been marked as a duplicate of bug 665055 ***