Re: punctuating with electronic commands

[Len Olszewski <saslpo -at- UNX -dot- SAS -dot- COM>]

> Here at IUPUI we have developed a set of documentation standards that we
> use consistently in every publication (user instruction-type).  We've
> also become to using graphical representations whenever and wherever
> possible.  For example, when stating something like "press the entery key" --
> we say    Press the <key graphic>

> For the sake of reader understanding we leave off the period at the end of
> the sentence whenever we end with a graphic.

> We also use BOLD CAPS to indicate something the user should type verbatim
> and lower case bold italics to indicate something the user should supply,
> such as type your user.id  (in this case your user.id would be in l.c. b.i.)


Yes, these are common syntax standards. We do it similarly here, except
we just use caps without boldface for items the user must type verbatim.
We enclose optional elements in angle brackets.

This would all be dandy if everyone read our "Using this Book" sections,
which explain font and syntax conventions for each book.  Of course,
nobody does. (This is a bitter little bit of exaggeration, but very few
people do, I suspect.)

Since a growing proportion of our software is window-based, with GUIs
and menus, we often represent what users should enter in the form of a
button path - a boxed series of text selections matching the point and
click choices on the screen, with little arrows between the boxes to
indicate order.

I don't know if a formal industry standard is the answer here, as
somebody suggested. Every product would, I suspect, need the freedom to
depart from the industry standard as its writers saw the need. The key
to any successful presentation strategy or font convention is
consistency within a document, or a series of documents. This usually
means a well-developed style sheet, or similar instrument. Since
products change over time, it also implies a process to assess and
replace obsolete syntax conventions as needed.
<-------------------------------^------------------------------------->
|Len Olszewski, Technical Writer |"That's a, I say, that's a JOKE,    |
|saslpo -at- unx -dot- sas -dot- com|Cary, NC, USA| son." - Foghorn Leghorn            |
|---------------------------------------------------------------------|
| Opinions this ludicrous are mine. Reasonable opinions will cost you.|
<-------------------------------v------------------------------------->