Hi,
I think that it's appropriate for examples to be specific rather than
generic. In fact, one might argue that the primary purpose of an example
is to turn the generic into the specific. I think that a precedent for
OS-specific examples exists every time an example includes a path with a
directory separator (\ for Windows and / for UNIX or LInux systems).
One possible solution would be to state in the explanation the OS to
which the example applies. Other possibilities are to include statements
such as "In this example, the domain directory is..." or "In this
example the software is installed in..." in the explanation of the example.
Let's discuss this issue further at the meeting.
Regards,
-Paul
June.Parks_at_Sun.COM wrote:
> I have an issue with "Examples contain only literal text, *no*
> placeholders." The locations of the installation directory and domain
> directory are different on different operating systems, so to show a
> literal example is to show an example for only one operating system.
> It would be rather tedious to show examples for all operating systems,
> and it would be a pain to change lots of examples when the paths for a
> given operating system change, which is why we have path variables in
> the first place.
>
> June
>
> Paul Davies wrote:
>> Hi,
>>
>> A first rough draft of the GlassFish v3 Documentation QA requirements
>> <http://wiki.glassfish.java.net/Wiki.jsp?page=GlassFishV3DocQuality>
>> is now available.
>>
>> Let's start discussing these requirements at our next meeting.
>>
>> Regards,
>>
>
--
Paul Davies, Senior Technical Writer, Sun Microsystems, Inc.
http://blogs.sun.com/techscribe/