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"

About

mkb

Search

Archives
« July 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
31
  
       
Today