Users vs. usage?

["Hart, Geoff" <Geoff-H -at- MTL -dot- FERIC -dot- CA>]

Shauna reports that she's writing "a System Functionality test" for a
"literalist user/tester base" (technophobic users, often unaware of half the
rules for grammatically-correct writing, and prone to avoid reading when
possible). (Sounds an awful lot like a typical audience to me! <g>) <<The
document convention... is that literal text to be entered into a control
during the test is enclosed in quotes. (This is in  part because the users
in question ignore or don't notice font changes or italics as emphasis in
this case.) Usage question: In this case, if it becomes necessary to include
a comma after the quote-enclosed text (for the sake of the appropriate pause
needed in the 
sentence describing the step to be taken), would you prefer to place it
inside or outside of the quote marks?>>

I'd prefer to avoid the issue entirely, since truly literal readers will
also type the quotation marks, no matter how carefully you explain that they
shouldn't do this. (Trust me... I've been working with a desktop publisher
for 10 years now, and despite repeated explanations of this convention, she
still doesn't get it.) My suggestion would be to communicate as clearly as
possible by formatting the instructions to the test participants in the form
of a two-column table. The left column contains the instructions, and the
right column contains what (if anything) the reader must type; depending on
the complexity of the text, you could conceivably add a third column with
mouse actions or other tips. In this approach, you don't have to apply any
formatting whatsoever to the literal text to be typed. You must, however,
make sure that the column titles for the table repeat on each new page, and
that you rewrite the text slightly to make sure that the literal text comes
at the end of a sentence, not in the middle. For example "Type XXX and press
return" would become two steps, the first being "Type the text at right:
XXX" and the second being "Press return: [nothing]", with the material after
the colon indicating what you put in the second column. If your audience is
really this literal--and some are--this probably represents an excellent
solution in the final documentation, not just in the test.

<<Grammar indicates it should go inside the quotes, clarity indicates it
should go outside the quotes.>>

Actually, grammar indicates no such thing; this is a _style_ question, and
modern usage differs between British-influenced and American-influenced
style guides, which (respectively) place punctuation inside the quotes only
if it belongs there and place punctuation inside the quotes all the time.
The British system is also called "logical" punctuation because it makes
logical sense to only include punctuation in quoted material if it really
belongs there, not because it's inherently superior to the American style;
it is, however, safer to adopt British punctuation in legal matters, where
the position of punctuation might be assumed to be very important indeed.

--Geoff Hart, FERIC, Pointe-Claire, Quebec
geoff-h -at- mtl -dot- feric -dot- ca
"User's advocate" online monthly at
www.raycomm.com/techwhirl/usersadvocate.html

Tarzan's rule of data processing: Never let go of one vine until you have a
solid hold of the next.--Anon.
 

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Be a published author!  iUniverse gives you: a high-quality paperback, a
custom cover design, and distribution to 25,000 retailers.  And it's
affordable.  Join our almost 10,000 published authors today.
http://www.iuniverse.com/media/techwr

  Your monthly sponsorship message here reaches more than
  5000 technical writers, providing 2,500,000+ monthly impressions.
  Contact Eric (ejray -at- raycomm -dot- com) for details and availability.

---
You are currently subscribed to techwr-l as: archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit 
http://www.raycomm.com/techwhirl/ for more resources and info.