Re: Better way to indicate a variable in doc

[Kevin McLauchlan <kmclauchlan -at- chrysalis-its -dot- com>]

On Thursday 24 October 2002 17:35, Paul Goble wrote:
[...]
> Will users attempt to type in your notation just as
> you wrote it? If that's a danger, sometimes it's
> better to use italics (or some other formatting that
> can't easily be typed) rather than % or <>.
>
> Is it possible to JUST use examples?  In your
> message, I found "Port 4 of 8 is not answering
> calls" much easier to read than "Port %s of %s is
> not answering calls."  If the user is trying to
> decode a message, they really don't need you to give
> an exact specification of the message format.  They
> only need to be able to recognize that the message
> in your document is "close enough" to the message
> they're worrying about.

When I was young and naive, I thought like that...

Shooosh!  Just kidding.  I'm in an especially Friday 
kind of mood. Fortunately it coincides with Friday 
where I happen to be, so...

Anyway, I tried the "obvious example" thing in 
a previous set of docs. It worked for most people.
However, Customer Support did receive a few 
early morning (or late night...) calls  -- funny, how 
the people who are determined to read your 
instructions in creative ways always work in 
the wee hours (perhaps there's a connection) -- where
the customer had bolluxed the install/setup by using
the example variables literally. Yes, I had written
 "...for example:" just before the examples.

So now, I use <something> for "stuff you type in" 
as part of a command-line operation, and "%" for 
for variables that would be passed from another 
operation, or picked up from a database, or similar.

And THEN I offer an example, as well.

So far... so good.

/kevin

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Buy ComponentOne Doc-To-Help 6.0, the most powerful SINGLE SOURCE HELP
AUTHORING TOOL for MS Word. SAVE $100 on the full version and $50 on the
upgrade.  Offer ends 10/31/2002 (code: DTH102250).
http://www.componentone.com/d2hlist1002

All-new RoboHelp X3 is now shipping! Get single sourcing, print-quality
documentation, conditional text and much more, in the most monumental
release ever. Save $100! Order online at http://www.ehelp.com/techwr-l

---
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.