Sun Cluster 3.2 Documentation Responses to Voice-of-the-Customer Feedback

Sun Cluster 3.2 is one of the most feature-rich releases in this product's history. The largest and most ambitious feature in the release was the new object-oriented command set. See A New Command Set for Solaris Cluster 3.2 for more information. This new set of commands required that the Sun Cluster writers modify every procedure in the Sun Cluster documentation suite and create over 30 new man pages. While this was a daunting task (over 2,000 procedures), the Sun Cluster writers decided to take advantage of this opportunity to address many of the comments and requests we have received from customers over the past few years.

First Request: Include More Examples

Many customers have asked us to include more examples in our documentation, especially in our man pages. In Sun Cluster 3.2, the Sun Cluster writers added examples to all of our new procedures and man pages. In addition, we went back and added examples to many of our existing procedures. We also added a new Quick Start Guide, which is a cookbook or example of how to install a common Sun Cluster configuration. Finally, we added examples of how to deploy hardware and data service (agent) configurations.

Examples of our new and improved documentation include:


  1. Quick Start Guide

    This guide is an example of a simplified Sun Cluster installation using a configuration used by approximately 80% of our Sun Cluster customers.

  2. "Sample Hardware Deployments" and "Sample Data Service Deployments" in Sun Cluster 3.2 Documentation Center

    Deployment examples provide samples of hardware and data service configurations.

  3. How to Install and Configure a Two-Node Cluster

    This "How To" provides simple instructions and examples for installing a two-node cluster.

  4. Examples in Object Oriented (1CL) man Pages and Quorum Server man Pages

    All man pages for the new object-oriented command line interface and the new quorum server feature contain comprehensive examples.

  5. Examples in All New Procedures Added for Sun Cluster 3.2 Features

    We added examples to the procedures for all new features in the Sun Cluster 3.2 release. In addition, we added examples to many of the existing procedures, as shown in Example 8.1 Live Upgrade to Sun Cluster 3.2 Software.


Second Request: Make Information Easier to Find

Someone wise once said, if you can't find the information, it might as well not be there. Many of our customers complained that it was difficult to find information in the Sun Cluster documentation. To help customers both identify and find the information they need, we created a Sun Cluster documentation center. This center provides a list of links to useful information. If you are a first-time user, we added a Getting Started section to help you ramp-up on Sun Cluster. Feel free to add your comments about this new navigation tool.

We also added information about using external browsers to search docs.sun.com. Now you can use your favorite search engine to search the Sun Cluster documentation.

Finally, we added the ability to view man pages from the procedural documentation. This ability was available in our core Sun Cluster documentation, but now we've added this ability to all our Sun Cluster product documentation. If there's a link to a man page in our documentation, just click on the link and the man page is displayed in the browser window. To view all of the man pages, click on the reference collection for the appropriate Sun Cluster product.

Examples of our improved documentation include:


  1. Sun Cluster Documentation Center

    This document provides a topic-based list of Sun Cluster information to help you find information in the Sun Cluster doc set.

  2. Searching Sun Product Documentation in Sun Cluster 3.2 Release Notes

    We added information to the Sun Cluster 3.2 Release Notes explaining how to use external browsers to search docs.sun.com index entries. This information will help you find the product information quickly and easily.

  3. Reference Collections for All Sun Cluster Products

    The addition of reference collections for all Sun Cluster products enables you to view relevant man page information in a browsable format from links in the user documentation.

    Sun Cluster 3.2 Reference Manual
    Sun Cluster Data Services Reference Manual

See my entry here next month for two other categories of customer comments we addressed in our Sun Cluster 3.2 documentation.

Rita McKissick
Sun Cluster Documentation

Comments:

I have a question that's kinda related to Documentation. What on earth is the product name? It seems that the names "Sun Cluster" and "Solaris Cluster" are now used nearly interchangeably in various materials. I suspect that "Solaris Cluster" is intended to refer to the suite that includes "Sun Cluster" and Geo cluster, but it's not made clear anywhere that I can see.

Posted by Boyd Adamson on April 25, 2007 at 09:17 AM PDT #

I agree, this is confusing. As of Sun Cluster 3.2, the suite of Sun Cluster products (framework, data services, and Geographic Edition) are being marketed under the name of Solaris Cluster, similar to their being marketed under the name of Sun Java Availability Suite. This was a late-breaking decision and we didn't have time to include this information in the product documentation. To add to the confusion, you will need to look under Solaris Cluster to find our Sun Cluster 3.2 and Sun Cluster Geographic Edition 3.2 documentation. However, both the product documentation and the product itself are consistent in their use of Sun Cluster 3.2.

Posted by Rita McKissick on April 26, 2007 at 04:23 AM PDT #

Boyd, I can give you the official answer or the unofficial answer. As this blog is an official blog, I'll give you the official answer. Your suspicion is correct. Solaris Cluster refers to the suite. Sun Cluster refers to the product itself. I will add, however, to gain insight into what my unofficial answer is, click on my name at the end of this comment for a recent blog I posted elsewhere about Sun's often frustrating penchant for dumping brand names.

Posted by Brian Keith, Technical Writer, Sun Microsystems, Inc. on April 26, 2007 at 04:30 AM PDT #

Hi Rita, While preparing for my SC 3.2 certification test, I spent a considerable amount of time reading through the 3.2 documentation set. I found tons of typographical errors in the documentation, and several of the examples contain incorrect output (there are a few places were the command output doesn't match what is being described in the document). I also noticed that information is repeated in dozens of places, and the admin guide and concepts guide have some conflicting information. Would it be possible to get someone to proofread the 3.2 documents again? Thanks, - Ryan

Posted by Matty on April 26, 2007 at 08:03 AM PDT #

Thanks for the information and link Rita and Brian. It seems that even those who write the product web pages don't understand the naming. Right now, at http://www.sun.com/software/solaris/cluster/index.xml we see:
Solaris Cluster is at the core of Sun Java Availability Suite along with Solaris Cluster Geographic Edition, Solaris Cluster Agents and Developer Tools.
And on the FAQ
The Solaris Cluster software is a framework that extends the high availability features of Solaris. It includes Solaris Cluster, Solaris Cluster Geographic Edition, developer tools ... Sun Cluster 3.2 is the latest release of the tested and proven Sun Cluster software.
I'd suggest that a paragraph on the product page that explains the naming might be good, but I'm not sure of the chances of it being correct

Posted by Boyd Adamson on April 26, 2007 at 08:37 AM PDT #

Ryan, thank you very much for your comments. My apologies for the mistakes. Books are considered closed once they are delivered for a release and we cannot reopen them due to resource constraints. However, we will make every effort to fix these mistakes in the next release. If you would like to give us some specific feedback on the docs, you can easily provide that feedback on docs.sun.com. When you find a problem, copy the url for the location, click the Send comments link (upper right-hand side of docs.sun.com webpage) and include both your comments and the location in the feedback information.

Posted by Rita McKissick on April 26, 2007 at 08:42 AM PDT #

Boyd, sorry about all the typos and errors that you found. However, that information is repeated in dozens of places is actually intentional, believe it or not. Each manual is intended for a specific audience. You're unlike many of our customers, who primarily and generally focus on one or two manuals and that's it. Your reading all of them is not unheard of, but unusual. :)

Please feel free to contact me directly (Brian.Keith@sun.com) if you like about the conflicts of information in the administration guide and concepts guide, as I'm responsible for the Concepts Guide. I would really be interested in hearing from you about these conflicts (and would like to make sure that I correct them).

And yes, it would be possible to get my editor to review the manuals for which I'm responsible for the next release. In which manuals did you find the typos and other errors?

Did you have a chance to look at any of the man pages? If yes, how did you find them?

Please feel free to contact me directly. I'd like to get a better idea of the scope of the problems that you found in the documentation.

Thanks!

Posted by Brian Keith, Sun Microsystems, Inc. on April 26, 2007 at 10:21 AM PDT #

Post a Comment:
  • HTML Syntax: NOT allowed
About

mkb

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today