Re: Better way to indicate a variable in doc

Subject: Re: Better way to indicate a variable in doc
From: Kevin McLauchlan <kmclauchlan -at- chrysalis-its -dot- com>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Fri, 25 Oct 2002 10:30:22 -0400

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.


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

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

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 for more resources and info.

Re: Better way to indicate a variable in doc: From: Paul Goble

Previous by Author: Re: Do choosy mother mothers choose GIF?
Next by Author: Re: Do choosy mother mothers choose GIF?
Previous by Thread: Re: Better way to indicate a variable in doc
Next by Thread: Which class

What this post helpful? Share it with friends and colleagues:

Sponsored Ads