Hi Vivek,
Thank you for this review. I have processed your comments as indicated
by my individual responses inline to your comments. The resulting draft
is attached in PDF format.
On 10/02/09 15:32, Vivek Pandey wrote:
> Hi Paul,
>
> Looks good. Here are my comments:
>
> "configure-jruby-container– configures the Enterprise Server JRuby
> container"
>
> - There should be a space after configure-jruby-container and between
> dash(-).
DISCUSS: The spacing around the dash is controlled by the tools. My
editor is investigating this issue with the tools team.
> - Why are you calling 'Enterprise Server' instead of GlassFish?
DECLINE: Enterprise Server is the name of the product to which this man
page applies. It would be unclear to call the product just ""GlassFish,
as GlassFish is a brand that applies to a wide range of products and
services:
* Enterprise Server
* Communications Server
* Enterprise Manager
* Portfolio
* Enterprise Service Bus
* Webspace Server
* Community
* Project
And there might be others.
Note that on the first use in the Description section, the product is
referred to by its full name: Sun GlassFishTM Enterprise Server.
>
> *--jruby-home*
>
> "The directory where the JRuby runtime interpreter is installed."
> Should be "The directory where the JRuby is installed."
DISCUSS: I have removed the words "runtime interpreter" from this
description, as they are incorrect. I will, however, clarify that what
is being specifed here is the location of JRuby itself, not the
Enterprise Server JRuby container. In the Description section, I have
also added an explanation of what we mean by Enterprise Server JRuby
container
>
> I think "However, the subcommand does not check for a JRuby runtime
> interpreter in the directory." can be removed, it makes it confusing.
> Isn't saying path to jruby installation is good enough.
DECLINE: The purpose of this statement is to preempt the question: Will
the command give an error if I haven't yet installed JRuby at the
specified location? I have changed the wording to say "However, the
subcommand does not check whether JRuby is installed in the directory."
>
> *--jruby-runtime*
>
> "To prevent runtime errors, this number must be greater than zero, at
> least the number that
> is specified by the --jruby-runtime-min option, and must not exceed
> the number that is
> specified by the --jruby-runtime-max option. The subcommand does not
> check that these
> conditions are met."
>
> Should be
>
> "Must be > 0 and >= --jruby-runtime-min and <= --jruby-runtime-max."
DISCUSS: As Kim mentioned, we don't use mathematical symbols. However, I
have trimmed and simplified this description.
>
> IMO, too many words make it more confusing. This way its clear as to
> what is expected.
>
> And the command should check the range and throw errors. If its not
> doing so then its a bug.
ACCEPT I have removed the statement that suggested otherwise. However, I
tried specifying an invalid value, and the subcommand seemed not
complain. I'll double-check and file an issue if necessary.
>
> *--jruby-runtime-min*
>
> "To prevent runtime errors, this number must be greater than zero, and
> must not exceed the
> number that is specified by the --jruby-runtime option or the
> --jruby-runtime-max
> option. The subcommand does not check that these conditions are met."
>
> just like --jruby-runtime, it can be concise:
>
> "Must be > 0 and <= --jruby-runtime and <= --jruby-runtime-max.
See responses to comments on --jruby-runtime.
>
> *--jruby-runtime-max*
>
> "To prevent runtime errors, this number must be greater than zero, and
> at least the number
> that is specified by the --jruby-runtime option or the
> --jruby-runtime-min option. The
> subcommand does not check that these conditions are met."
>
> should be
>
> "Must be > 0 and >= --jruby-runtime and >= --jruby-runtime-min."
See responses to comments on --jruby-runtime.
>
> I see there is short form mentioned with all of these commands. This
> is not implemented or not planned to be implemented so wondering why
> you have it in man pages?
ACCEPT: I have removed these short forms.They were in the usage message
that is displayed if the command is typed incorrectly. I have filed
Issue 9957 <
https://glassfish.dev.java.net/issues/show_bug.cgi?id=9957>
against the command.
>
> *--show*
>
> "Specifies whether the current settings of the Enterprise Server JRuby
> container are
> displayed."
>
> Why you have "Enterprise Server" instead of "GlassFish"?
See earlier response.
>
> Perhaps this is much easier to read: "Displays current setting of
> GlassFish JRuby container."
ACCEPT, with the exception of the change to the product name.
Regards,
--
Paul Davies, Senior Technical Writer, Sun Microsystems, Inc.
http://blogs.sun.com/techscribe/