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:punctuating with electronic commands From:Michele Berkes 615-576-2352 <BERKESM -at- A1 -dot- OSTI -dot- GOV> Date:Fri, 2 Apr 1993 16:48:00 EST
One of the topics that Eric brought up when he announced this list is
* I still cannot decide how to include commands in sentences without
either confusing readers, ignoring the rules of English grammar, or
I believe that a standard (set of conventions) needs to be created and we
(technical communicators) should start using it consistently. After all, we
all know to use a period at the end of a sentence and that italics indicates a
title of a book because we were taught that that's what they mean. (Of course,
GPO specifies to use quotation marks with book titles, but let's not muddy the
water with that issue now. Either way, the reader and writer understand.)
On a practical level, this issue has come up in a number of ways for me
recently. I'd like to hear how others are coping with this problem. How would
you handle the following?
"Send questions to username -at- xxx -dot- xxx -dot- xx More text here. More text here."
[what do we do here? ^]
This is a shortened version of an actual case. Because of space and
design, I cannot display the e-mail address on a separate line. The
sentences that follow must be there, so I do need some sort of
punctuation. The writer suggested leaving a space between the address and
the end-of-sentence period (shown below). Any reactions?
"Send questions to username -at- xxx -dot- xxx -dot- xx . More text here. More text here."
"To execute this command, type xxx and press return."
To call attention to the text to type since it is buried in a sentence, do
you capitalize it? (The system is not cap sensitive.) Do you set it in
bold or another typeface? How do you handle the name of the return key? We
use angle brackets and caps to indicate the names of keys, i.e., <RETURN>.
Do you like this? Any other ideas?
I'm looking for practical solutions, but more than that, I'm hoping to provoke
a debate. Has anyone come up with some general solutions to these issues?
Anyone have some other issues to bring up? I'd also be interested in hearing
ideas about an appropriate authority to document standards. (Discussions at a
Society for Technical Communications conference or a computer publishers
meeting or some other group? I hear _Words Into Type_ is being revised as we
speak--perhaps the editors there are considering this issue. Anyone know?)
Oak Ridge, TN
berkesm -at- a1 -dot- osti -dot- gov