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,
--
Paul Davies, Senior Technical Writer, Sun Microsystems, Inc.
http://blogs.sun.com/techscribe/