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: Conventions for denoting typed commands etc. From:K Watkins <KWATKINS -at- QUICKPEN -dot- COM> Date:Mon, 23 Oct 1995 15:16:00 -0300
Traci,
There is no set of common conventions. Witness the fact that many user
manuals have a short section up front to describe the conventions they use.
But I'm not sure how many people other than us documentation weenies look at
those sections. The main advantage of such a section may be that it forces
the writer to ensure consistentcy.
One system I saw, which I liked at the time - though it makes less sense
now that there are fewer people out there who have ever used a typewriter -
was to use Courier (the standard typewriter-style font) to indicate text
which the user should type. This text for the user to type was always on a
line of its own. Variables appeared in italics of whatever font the body
text was in, such as Times. The italic Times made it plain that the
variable was different from the rest of the stuff the user should type,
while its presence in the "type this" line made it plain that it was part of
what the user had to do. The sentence(s) right after the "type this" line
always explained the variables, if any.
In this system, I suppose that the names of buttons and other replicas of
screen text would appear in a font resembling the actual screen font, so
long as that set them apart sufficiently - for instance, if the program you
are documenting uses a sans serif font for display, and your text is in
Times. Otherwise you might have to fall back on bold etc.
I generally avoid all caps; it gives undue emphasis to the text. Even
when using bold to mark screen text, I sometimes use it a point size or two
smaller than the rest of the text to keep it from seeming disproportionately
important. For instance, in "press the F7 key," if I were marking key
names, I might put the body text in 12-point, and then have "F7" in 10-point
bold.
On 21Oct95, Traci Eyer (teyer @ holly.colostate.edu) wrote:
>I'm writing my first piece of simple computer documentation, and I got to
>thinking that there must be some fairly conventional ways to denote a
>typed command or a button or a screen title, etc., in documentation, but
>using bold letters, or all caps, or italics.
