Re: documenting parametised messages

Subject: Re: documenting parametised messages
From: Dick Margulis <margulis -at- fiam -dot- net>
To: "TECHWR-L" <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Mon, 26 May 2003 18:19:33 -0400




David O'Brien wrote:

We are creating a document that includes error messages, the situation that led to the message and available solutions. In many cases the error message is generated from a single parametised phrase, such as "Expected (0) values but only (1) were provided". This could manifest itself to the user as "Expected 3 values but only 2 were provided" or something similar.

Does anyone have experience or suggestions as to how this should be documented? e.g., insert typical values with notes explaining possible variations, keep the the parameter entry points (probably not a good idea) or something else?



David,

Know thine audience.

In similar (not identical) situations, I've taken the algebraic approach, using italic n, m, p, etc. to represent as many variable values as there might be in the expression. So, in your example, I would write "Expected _n_ values but only _m_ were provided." That would still require an explanation, and it is an approach I would use _only_ if I were confident that such notation would be familiar to the audience. If I were writing a help file for low-skill data entry clerks, I would not use algebraic notation.

Dick


---
[This E-mail scanned for viruses at mail.fiam.net]


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Robohelp X3, from eHelp, lets you quickly and easily create professional Help systems for all your Windows and Web-based applications, including Net.
Order RoboHelp X3 in May and receive a $100 mail-in rebate, PLUS
free RoboScreenCapture and WebHelp Merge Module.
Order RoboHelp today: 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.



References:
documenting parametised messages: From: David O'Brien

Previous by Author: Re: PowerPoint advice
Next by Author: Re: You're SUPPOSED to have good communication skills if you're a tech writer]
Previous by Thread: documenting parametised messages
Next by Thread: You're SUPPOSED to have good communication skills if you're a tech writer


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


Sponsored Ads