Re: Conventions for denoting typed commands, etc., in docs?

[Tamara Peters <1455 -at- MN2 -dot- LAWSON -dot- LAWSON -dot- COM>]

Traci, I have done computer documentation at three very different
companies. The strongest arguments I have heard about buttons, screen
titles, or commands are to type it as it appears to the user (or as the
user has to type it). I avoid bold, italics and all caps, because they
seem to litter the page after awhile.

Having said that, the company I am currently at has a rather complicated
system for writing up Unix commands: bold for something the user types
exactly as you show it in the documentation, italics for a placeholder
(such as FileName) that the user replaces with the actual name, and all
caps, regular type for something they can type exactly as you document it
but which is perhaps a system variable representing a path. And then,
because it is Unix and therefore often case-sensitive, we use all caps if
it must be typed all caps, Uc/lc if it is case sensitive, and lowercase
if it doesn't matter or it must be lowercase.

Whatever you do, the best thing is to be consistent and explain it to
your readers in the introduction.

Hope this helps!


 ----------
From:  TECHWR-L[SMTP:TECHWR-L -at- VM1 -dot- ucc -dot- okstate -dot- edu]
Sent:  Saturday, October 21, 1995 3:30 PM
To:  Multiple recipients of list TECHWR-L
Subject:  Conventions for denoting typed commands, etc., in docs?

Hello! I've lurked for months and I've finally come up against something
I could use some help on. (Yes, I'm a student, one of those
non-traditional undergrads, too.)

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.

Can anyone help me out here?

Thanks!
Traci Eyer
teyer -at- holly -dot- colostate -dot- edu