Friday Jun 01, 2007

Requirements and Restrictions: Do You Really Mean It?

"I meant what I said, and I said what I meant.
An elephant's faithful, one hundred percent."
- Dr. Seuss, Horton Hatches an Egg


There are a lot of components that Sun Cluster brings together to work in a cluster as a whole. To make sure that all these components function correctly as a whole, the Sun Cluster engineers have identified a set of requirements and restrictions when configuring and running a cluster. Some of these requirements and restrictions are not very popular with users, which sometimes raises the question, "Is that really a requirement or is it just a recommendation?".

Writers Should Not Say "You Should"

Current Sun Tech Pubs style is, "Do not document recommendations." "You should do this action" is not precise enough wording. It leaves you the choice of not doing the action without explaining the consequences or alternatives. So instead, we document these two possible kinds of instructions:


  • A requirement or restriction. You must do or you must refrain from doing this action. It is not optional or negotiable. Engineering means it.

  • A guideline or set of choices. You can choose whether or not to do this action or choose between multiple possible actions. We also provide the information you need to make the decision.

So when we say things like "do not enable Solaris interface groups" or "all cluster nodes must be connected to at least one public network", it is mandatory.

Not Convinced?

But what if you feel you have a legitimate challenge to a documented requirement or restriction? It's possible that information that was documented a few releases ago is no longer valid for the current release, but it was overlooked during the latest doc reviews. Or maybe you want to understand the reason for a restriction but an explanation for it isn't documented.

The first thing you can do is to check whether anyone else has filed a doc bug about it. If you find an existing bug, the bug report will tell you whether the issue is being investigated or whether the information was confirmed as correct. If no bug exists yet, you can file one to alert Pubs about your concern. Alternatively, you can use the Send comments link on docs.sun.com, or post a comment on this blog site or on any other community where Sun Cluster engineers have an active presence.

Technical writers know that it is critical that the information we provide be accurate, complete, and precise. We work closely with development, QA, and any other educated eyes we can find to get the documentation as close to perfection as humanly possible.

So when you read a Sun Cluster requirement or restriction, you can believe it. We do.

Lisa Shepherd
Sun Cluster Technical Publications
"We're the M in RTFM"

Friday Apr 27, 2007

Tips and Tools to Search in Sun Cluster 3.2 Documentation

As a writer for Sun Cluster software, I am constantly looking up information in various manuals and man pages on docs.sun.com to check facts and provide references. I've learned a few ways to help speed up my information search.

Use Browse Product Documentation to search a whole documentation set

The default docs.sun.com search choices are to search all titles in docs.sun.com or to search within a book or collection that is already displayed. But there is also a way to search within a specific documentation set or product line.

Say you are looking for information about HAStoragePlus. You found it once before in a Sun Cluster 3.2 document, but you can't remember which document that was. Was it in a data-service book, a man page, the system administration guide? Since you know the product and release you want to search in, go to the Browse Production Documentation tab of docs.sun.com. From here you can search all collections that belong to the Sun Cluster 3.2 release, but ignore everything else.

To display the entire Sun Cluster 3.2 documentation set, drill down to Software > Enterprise Computing > High Availability/Clustering > Solaris Cluster > Solaris Cluster 3.2. You'll see "Solaris Cluster 3.2" in the Within search field. From here, in a single search you can look for "HAStoragePlus" throughout the Sun Cluster 3.2 hardware, software, data service, man page, release notes, and Geographic Edition collections.

Note: Don't get confused when you see "Solaris Cluster" instead of "Sun Cluster". The product software uses the name Sun Cluster 3.2, as does the documentation. But the suite of Sun Cluster
3.2 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. It's all the same thing.

Use the Index when a word you search for isn't found

Although "One Term, One Meaning" is an ideal that technical writers aspire to, features can end up being called different names by different groups when a product is finally released. So the feature name you are used to using during development or Beta might not be the formal name used in the final product documentation. A look in the index of a book that is likely to document the feature could help you find the formal name of the feature you want to read about.

For example, a file system that is configured with HAStoragePlus is informally referred to as a "failover file system". A search for that term in the Sun Cluster 3.2 doc set finds hits in two books. Follow the hit in the Software Installation Guide to the index, and there you will see "failover file system, See highly available local file system". Run your search again on "highly available local file system", and you will get several hits instead of two.

Looking up a familiar term can also be helpful by showing you other possible index terms to look under. For example, the index listing for "installing" might include "See also adding" and "See also configuring". You can look up these additional terms if you don't quite find what you are looking for under "installing".

Use the Documentation Center for quick links to frequent topics

The Documentation Center is a new reference tool in Sun Cluster 3.2. This web page provides links to information at different levels of the documentation, grouped by topic or purpose. If there is an important feature you want to look up, you can probably find a link to it in the Sun Cluster 3.2 Documentation Center.

Use an external search engine

If you prefer, you can use an external search engine to locate information on docs.sun.com. Include "site:docs.sun.com" in your search criteria, and the search will be conducted only on docs.sun.com documents. Also include "Sun Cluster 3.2" and the search will hit mostly or only documents in the Sun Cluster 3.2 doc set.

Restore missing bullets

This is a readability tip rather than a search tip. A lot of Sun Cluster documentation uses bulleted lists to organize information and make it easier to read or scan. But sometimes on my browser the bullets don't display, leaving me with indented paragraphs that are hard to read. If that happens to you, just press Shift-Reload and the bullets should show up.

Learn how the docs.sun.com search works

The search syntax that docs.sun.com uses is very different from most search engines, especially how it interprets special characters. To avoid frustration, click the Search tips link, just under the search field on any docs.sun.com page, and read about how docs.sun.com works.

Tell us what you want

There is a Send comments link on the same line and to the right of the Search tips link, on any docs.sun.com page. This takes you to a feedback site for both documentation content and website functionality. If you are reporting an error in a book, or like something and want to see more of it, include the URL or the book and section title that you are talking about. Unfortunately, the Send comments site is not aware of what web page you are in when you click the link, so you have to provide that information in the Comments field.

I hope these tips help you find more quickly and easily the Sun Cluster 3.2 information you need.

Lisa Shepherd
Sun Cluster Technical Publications
"We're the M in RTFM"

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

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