Hi June,
The presence of the qualifier "Try to" in the text on page 144 is an
acknowledgment that in some situations it might not be possible to
follow this guideline. Also, I believe that the phrase "code variables"
denotes environment variables that are defined in the software (such as
$JAVA_HOME) rather than replaceable items such as /as-install/. However,
as we have already discussed, it's probably not a good idea to invent
our own environment variables just for the purposes of the documentation.
There's no such qualifier in the guideline on page 105 that I cited,
suggesting that the guideline is to be followed at all times.
Regards,
-Paul
June.Parks_at_Sun.COM wrote:
> On page 144, the style guide also says, "Try to use code variables
> instead of specific operating system, platform, or address space text
> in examples. The use of variables avoids duplicating information."
>
> June
>
> Paul Davies wrote:
>> Hi June,
>>> It is my understanding that the intent of making examples literal is
>>> to allow users to use them as is, to copy and paste them. This is
>>> great when it's possible. With AS-specific paths, it's often not
>>> possible.
>> I do not share your understanding.
>>
>> The purpose of making the examples literal is to turn something
>> inscrutable like /as-install/ into something that from its format is
>> obviously (in this case) a directory.
>>
>> The style guide that we're following on the GlassFish project
>> supports this viewpoint. Page 105 of /Documentation Style Guide for
>> OpenSolaris/ (PDF)
>> <http://opensolaris.org/os/community/documentation/files/OSOLDOCSG.pdf>
>> states:
>>
>> When providing an example, follow these guidelines:
>> ...
>> Use practical data in the example rather than replaceable or
>> variable text.
>>
>>> It seems to me there's no advantage in being literal when the user
>>> has to substitute values that apply to him or her anyway.
>> So why include any examples at all? After all, how many users will
>> have a file that is named MyWSDemo.java to compile?
>>
>> Regards,
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: docs-unsubscribe_at_glassfish.dev.java.net
> For additional commands, e-mail: docs-help_at_glassfish.dev.java.net
>
--
Paul Davies, Senior Technical Writer, Sun Microsystems, Inc.
http://blogs.sun.com/techscribe/