If standard environment variables exist, we should use them, and they
would be preferable to replaceable text. There may well be such
variables. I'm not sure because I haven't documented them.
Page 117 of the style guide actually shows replaceable text being used
in a command line. Does this somehow not count as an example? Is it
considered to be something else, such as a syntax display?
I searched the style guide for an explanation of how replaceable text
should be used. There are mentions here and there, but no full
explanation. Not being able to use them in command lines especially
makes their use quite limited. I suspect this is probably not the
intent, though, because there are some replaceable text variables
defined for standard use.
June
Paul Davies wrote:
> 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
>>
>