Friday Jun 08, 2007

Sun Cluster 3.2 Doc Responses to VOC Survey - Part 2

This blog continues my discussion of the improvements that we have made to the Sun Cluster 3.2 documentation in response to a Voice of the Customer survey.

We identified four major customer requests in the VOC survey. For information on our response to the first two VOC requests, see Sun Cluster3.2 Documentation Responses to Voice-of-the-Customer Feedback.

Third Request: Provide Task-based Information

This VOC survey was designed to cover several Sun products. Fortunately, Sun Cluster procedural documentation is already task based, so this was an easy request for us. Sun Cluster introductory information and conceptual information that is not relevant to a specific task is provided in an introductory chapter or the Overview document. This separation of procedural and introductory information makes the procedures shorter and more concise.

Let me know if you think this separation in our documentation works well for you.

Fourth Request: Provide More Information for the Novice User

The original Sun Cluster documentation was targeted toward a sophisticated, well-trained, UNIX-savvy system administrator. Sun Cluster required that the customer receive extensive training before using the Sun Cluster product. As a result, our documentation tended to assume a high level of knowledge and some of our customers started to complain. Customers, it seemed, did not want to be required to hire senior system administrators to manage their clustered environment. And even the senior system administators did not always have the UNIX experience we required. Customers also told us that the person trained on Sun Cluster might not be the person who administers the cluster. As a result, we've added several documents to help the new cluster system administrator to quickly ramp up and get started with Sun Cluster.

Here are some examples of our new and improved documentation:

  1. Sun Cluster Documentation Center

    This topic-based document helps novice users to find information more quickly in our Sun Cluster doc set. The documentation center begins with a Getting Started group of links specifically targeted for novice users.

  2. Sun Cluster Overview

    This guide provides information on the Sun Cluster product along with an introduction to key concepts and the Sun Cluster architecture.

  3. Quick Start Guide
    The Quick Start Guide provides detailed, easy-to-follow steps to install Sun Cluster in a configuration used by approximately 80% of our Sun Cluster customers.
  4. (how-to) How To Install and Configure a Two-Node Cluster

    This "How To" provides simple task-based instructions for installing a two-node cluster.

  5. Quick Reference Card

    The Quick Reference card provides simplified steps to perform the most commonly used Sun Cluster tasks. This card is available in a customized format to make printing easier.

  6. Intro(1CL) man page

    This man page describes the new object-oriented command set for Sun Cluster 3.2. This man page also defines each of the new commands, provides short versions of the commands, and provides links to the command man pages.

  7. Object-Oriented Commands appendix

    This appendix is included in each of our procedural docs and provides a quick reference to the new object-oriented commands in Sun Cluster 3.2. The appendix lists the command short forms, and their subcommands.

If you have any suggestions for other documentation that will help novice users, feel free to comment.

Rita McKissick
Sun Cluster Documentation

Wednesday Apr 25, 2007

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 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 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


Oracle Solaris Cluster Engineering Blog


« September 2016