Re: Quotes/Comma question

[Mary Ellen Schutz <me -dot- schutz -at- juno -dot- com>]

Darren Butler writes:
Please help settle a debate. Is it correct to follow quotation marks with
either a comma or a semi colon?
When the Test Path screen appears, type
"C:\Applications\testprograms\TS3.exe", then select NEXT.

Gene Kim-Eng writes in part: 
I was taught that a comma should be used, inside the right quotation
mark.
~~~~~~~~~~~~~~~~~~~~~~~~~
 
According to US English conventions, the comma (or semicolon) would be
inside the quotation mark, but I can foresee a problem when the manual
reaches the end user.  You are giving them instructions to enter a
specific string and the sentence punctuation then appears to be part of
the string. 

Having written for the Air Force in my day, lead writer on an Air Force 3
computer contract many, many moons ago, I'd suggest recasting the
sentence as:
When the Test Path screen appears, type
"C:\Applications\testprograms\TS3.exe" and then select NEXT.

While either a semicolon or a comma could be used, let's face it, "Then,
select next." can stand on it's own, introducing either and maintaining
standard US English grammar conventions will introduce confusion and
cause failures.  The punctuation will, inevitably, be typed by at least
some users, right along with the rest of the path string.  Bingo! Nothing
works.

The best solution would be to eliminate the quotes and change the font
for user entries, as Janice Gelb suggested. But even that convention may
result in the following punctuation being added to the string, as not
everyone has a fine eye for punctuation fonts.  You may not be able to
change that convention, though.  

We had a major involved in the project who insisted on no subheaders in
any procedure.  The hard drives that were to be installed needed to be
manually configured differently, depending on the position in the drive
train, the vendors represented in the drive train, and whether it was
Tuesday or not. (True, plug-and-play was only a gleam in some engineer's
eye.) When the documentation went out for test, not a single drive
installed correctly.  The AF techs read as far as the first illustration,
popped the drive in, and voila...nothing worked.

I asked them to retry the procedure, following the instructions,
step-by-step, and voila...everything worked. "There was nothing in the
documentation that made us think we actually had to read it."  One major,
hot on my case to FIX IT.  Subheaders that appeared in the table of
contents, as well as the procedures, fixed it just fine. (Yes, it does
pay to save proofs.) A new set of techs tested the documentation and
installed the drives with nary an fault.

Air Force mentality or no, adding punctuation that is not part of a
string inside the quotes, when you are using quotes to indicate
key-by-key data entry, spells foreseeable failures for end-users.

ME

Mary Ellen Schutz, your Gentle Editor
Gentle Editing, LLC
www.GentleEditing.net
608.695.8254
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
It is easier to build strong children than to repair broken
men...Frederick Douglass
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Create HTML or Microsoft Word content and convert to Help file formats or 
printed documentation. Features include support for Windows Vista & 2007 
Microsoft Office, team authoring, plus more.
http://www.DocToHelp.com/TechwrlList

True single source, conditional content, PDF export, modular help.
Help & Manual is the most powerful authoring tool for technical
documentation. Boost your productivity! http://www.helpandmanual.com

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to 
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwr-l.com/ for more resources and info.