Lloyd Chambers wrote:
> To clarify my earlier comment—
>
> "If the user needs more info on any particular option, man page should
> provide all the details needed"
>
> In my experience the issue is rarely understanding a particular
> option, the major stumbling block is lack of a basic and advanced
> *example* invocation.
Not sure what you are trying to say. Probably we are saying the same
thing. :)
If I were to sum up my previous thoughts, it would run something like:
Usage should be concise and precise. Though not a widely followed
practice, merging usage and example seems convenient to me because then
as a basic user I get a very good quick reference from the usage itself.
At times, I have found it inconvenient to see the whole man page just
for the examples; nonetheless I do expect of myself to see man page for
any specific details especially when the text is lengthy.
Getting to see the defaults then and there also makes up for v3 user
experience degradation, if any, due to missing default values in domain.xml
Anyway, my vote is inherently biased being very close to the product. So
I'll save meself further typing ;-)
> Lloyd
>
> On Oct 23, 2009, at 10:08 AM, Lloyd Chambers wrote:
>
>>> [Thinking aloud] It sure does give more info. But if there were
>>> bugs, as docs team stated, because someone used 4848 as is, this
>>> kind of nomenclature as well as the one above seems to have a high
>>> bugs potential. Plus some of the commands with many options are
>>> already pretty lengthy. Such verbose usage will reduce the usage
>>> reference appeal further. To me, usage has to be short as it is a
>>> means of quick reference. If the user needs more info on any
>>> particular option, man page should provide all the details needed.
>>> But then again any existing standards and practices on this may have
>>> better reasons to support such detailed usage text.
>>
>
> Lloyd Chambers
> lloyd.chambers_at_sun.com
> GlassFish Team
>
>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: admin-unsubscribe_at_glassfish.dev.java.net
> For additional commands, e-mail: admin-help_at_glassfish.dev.java.net
>