RE: How would you handle this?

Subject: RE: How would you handle this?
From: "John Bartol" <jbartol -at- sierrawireless -dot- com>
To: "Jessica Weissman" <Jessica -dot- Weissman -at- hillcrestlabs -dot- com>
Date: Wed, 13 Sep 2006 13:08:37 -0700

Hi Jessica.

I think what you need to do is rephrase the statement.

The java doc page for ClassFormat doesn't actually refer to 'greater than' with respect to the '<'. In the example they give:
ChoiceFormat fmt = new ChoiceFormat(
"-1#is negative| 0#is zero or fraction | 1#is one |1.0<is 1+ |2#is two |2<is more than 2.");

(Make a special note of the third and fourth limit/string pairs: "1#is one" and "1.0<is 1+". It's important a bit further down.)

The operator ('#' or '<') is used to compare an argument passed to the 'format' method ( for example: fmt.format(1.5) ) with the '*lower* limit' value on the left side of the operator.

The '#' operator means "This or higher".
The '<' operator means "The next 'double' after the limit value, or higher.

If the argument is less than the first limit value, then the first limit is used. If it is greater than the last limit value, the last limit is used. Thus, again from the doc page (paraphrased), the following are the returned strings for the specified argument values:

'negative infinity' returns "is negative" <-- it's less than the first limit (-1), so the first limit is used.
'-1.0' returns "is negative" <-- it's the same as the first limit.
'-0.5' (I believe, it's not in the doc) returns "is negative" <-- it's "higher" than the first limit, "lower" than the second
'1.0' returns "is one" <-- it's the same as the 3rd limit. Here's where it gets a bit weird... it looks the same as the 4th limit, but the operator on the fourth limit is '<', which means the fourth limit is actually 1.0000000...0001 (the next double past 1.0), which leads us to...
'1.0000000000...001' through '1.9999....99' ---> these all return 'is 1+'

And so on.


So, to make a long story short (too late), I'd suggest not using 'equal' and 'greater than' to describe the operators. Fiddle with the example text ('this or higher', 'next double, or higher') to find something that works, and then test it on one of your java programmers, preferably one who is not already familiar with the use of the class.




________________________________

From: techwr-l-bounces+jbartol=sierrawireless -dot- com -at- lists -dot- techwr-l -dot- com on behalf of Jessica Weissman
Sent: Wed 13/09/2006 11:12
To: techwr-l -at- lists -dot- techwr-l -dot- com
Subject: How would you handle this?



Below is an extract from some programmer-written documentation that I am
assigned to clean up. Notice that at the end of the third line it says
" and '<' for greater than". Yes, it uses the lessthan sign for greater
than. In defense of my colleague this is from the Java message spec.
He did not implement it this way.

What I've done is insert a footnote saying "This is not a misprint. '<'
really does mean 'greater than' here. See [URL to java documentation
page]

Is this the best way? I don't want to break the example flow, but I
don't want to lose the information or have people either miss it or
write it up as a bug in the documentation. I think a footnote works
well. What do you think?

Thanks,

Jessica Weissman
*****************************

The detail part of the choice type element contains a list of choices
separated by the pipe ( | ) character. Each choice consists of a
number, an equality operator (which may be '#' for equals and '<' for
greater than), and a format string.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as jbartol -at- sierrawireless -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/jbartol%40sierrawireless.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.




^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

WebWorks ePublisher Pro for Word features support for every major Help
format plus PDF, HTML and more. Flexible, precise, and efficient content
delivery. Try it today! http://www.webworks.com/techwr-l

Easily create HTML or Microsoft Word content and convert to any popular Help file format or printed documentation. Learn more at http://www.DocToHelp.com/TechwrlList

---
You are currently subscribed to TECHWR-L as archive -at- infoinfocus -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40infoinfocus.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to lisa -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/techwhirl/ for more resources and info.


References:
How would you handle this?: From: Jessica Weissman

Previous by Author: RE: Definition of Technical Writer
Next by Author: Re: Music choices
Previous by Thread: How would you handle this?
Next by Thread: RE: How would you handle this?


What this post helpful? Share it with friends and colleagues:


Sponsored Ads