TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
It's always useful to have someplace the list of legal limits or whatever --
max size of this, minimum requirement for that. That type of information
tends to be a little abstract, however, and what's probably useful is to
note as you go what the effect is of that limit. Not just "maximum size of
string in a variable = 64K", but "you can join strings together with the
xxxxx operator, up to the maxiumum variable-size limit of 64K". You know,
stuff like that. Even slightly more abstract, and less popular yet with the
marketeers, is anticipating where they *might* have problems and trying
to warn them. A mythical example that would probably not be allowed:
"Display bitmaps with the xxxxxx command. This process requires substantial
memory, so if you do not have at least xxxxxxx of RAM, you might experience
out-of-memory errors when attempting it." Nonetheless, technical support
is always grateful when you've attempted to tell people where they might
approach limits.
-- Mike Pope
mikep -at- asymetrix -dot- com
----------
>From: TECHWR-L
>To: Multiple recipients of list TECHWR-L
>Subject: Limitations where?
>Date: Sunday, April 10, 1994 9:38AM
>When writing about a product or a program, where do you normally
>include its limitations?
>** All kinds of places, depending on when the user needs to be told or
> reminded of the limitation. Examples:
> IN ADVANCE:
> "This is a kosher turbo-oven and will reject all pork products."
> -- Right up front. Someone may want to return the
> machine immediately. Put the note at the start of the
> manual, prominently in the ReadMe, and/or even in the marketing
> materials.
> DURING OPERATION:
> "For health reasons, be sure not to undercook pork products."
> -- Some relevant place in the body of the instructions, such as
setting
> the timer. Could be in the ReadMe too.
> NEVER:
> "If the pig won't fit into the oven, don't climb in and try to
> pull it after you."
> -- Appendix or ReadMe.
> The midground is where the issue gets tricky. On the one hand, some
> operational provisos could be relevant to many different procedures
> and can seem too prominent if you repeat or reference them too many
> times, while on the other hand an "Always Remember The Following Stuff"
> section on page 5 won't help the user on page 87.
> Also, marketing people may tell you to downplay the limitations, while
> R&D people may warn you (or worse yet, may not warn you) that the
> limitations are difficult to calculate and subject to change during
> the life of the manual.
>__________________________________________________________________________
>Mark L. Levinson, SEE Technologies, Box 544, Herzlia, Israel
>mark -at- dcl-see -dot- co -dot- il | voice +972-9-584684, ext. 230 | fax +972-9-543917
