TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
Subject:Re: Representing Computer Interactions From:scot <scot -at- HCI -dot- COM -dot- AU> Date:Thu, 18 Jan 1996 15:45:16 +1100
>>The format that I have seen most often (and which I use) is:
>>
>> Select File|Open|SOME.FIL
>>
>>The use of the vertical bar as a seperator is useful because it is
>>grammatically uncommon (I believe it has some obscure phonetic
>>application) and catches the eye enough to differentiate the various
>>menu levels.
>True...however there is one potential point of confusion which may arise
>from this usage. The vertical bar is used in UNIX command syntax to
>signify the "pipe" command, and therefore I would hesitate to use it in doc
>for any sort of UNIX-based application.
This is also true for MS-DOS.
>I avoid using colons when writing Mac documentation because the colon is
>sometimes used as a separator in Mac pathnames. My favorite separator for
>command names is the logical-greater-than (>) symbol, either on its own or
>preceded by a hyphen or two (-->).
Just as bad (if not worse for reasons outlined below), I'm afraid. The
greater-than symbol is a output redirection in both UNIX and DOS. eg;
leaves you with a file called 'dump.the.output.into.this.file' which
contains the output of the traceroute command. Thsi is true even if you type
traceroute hci.com.au > ls
That would leave a file called 'ls' with the traceroute output in it. If
just happened to be superuser and were sitting in /usr/bin directory (or
where ever ls might live on your UNIX system, but that is typical), typing
the command as above would leave you with a totally dead ls binary (well,
ex-binary). In fact, you DON'T need to be superuser, you just need to have
write permissions to the 'ls' file. At least
traceroute hci.com.au | ls
won't kill the ls file, so the pipe is safer, even if it DOES confuse the
reader, they're not likely to murder existing files with it.
Similarly, the less-than sign gives you input redirection; eg.
/usr/lib/sendmail -s'hi there' scot -at- hci -dot- com -dot- au <pre-written.message.file
If I can, I use a bullet font or something to indictate separations between
commands to be typed. Either that, or a command to a line.
