Acronyms in documentation (was RE: Need some help for SRS

[Mailing List <mlist -at- ca -dot- safenet-inc -dot- com>]

John, prompted by Manisha's unattributed use of "SRS" wrote:


> I'd venture to add that the message is a prime example of 
> what makes so
> much of our documentation crap:  
> 
> The assumption that 4,000 people all know and agree on what SRS means.
> How much other content does this person write where it is assumed that
> something is known without establishing it.
> 
> At worst case, we all know that the first use of an acronym should be
> spelled out.

That was always my practice in paper and PDF docs, but 
what's "best practice" in Help?

A user may first encounter an acronym on any page at all, 
since there's no obvious preferred order in which to read 
Help pages.

If it's a frequently used acronym or abbreviation, it 
might get a little annoying to make every occurrence a 
link to the glossary.

What do others do? First occurrence on every page is a link?
Other approaches?

And in general, I've heard of two schools of thought:

a) in Help, you should make extensive use of linking since, 
	after all, hyperlinking is one of the major benefits 
	of Help/html, and yes, people jump in anywhere and 
	they need guidance wherever they are

VERSUS

b) in Help, you should minimize "busyness" and visual 
	clutter on your pages, so too many links is a no-no.

Some might say "well, take the middle path", but others 
might respond that it's more important to be consistent 
in your approach and presentation, so that users always 
know what to expect.

So, if I haven't put enough words into everybody's mouth, 
what do y'all have to say for yourselves?

Regards,

/kevin (not in USA, but not in India, either  :-)

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

ROBOHELP X5 - ALL NEW VERSION. Now with Word 2003 support, Content 
Management, Multi-Author support, PDF and XML support and much more! 

Now is the best time to buy - special end of month promos, including:
$100 mail-in rebate; Free online orientation on content management
functionality; Huge savings on support and future product releases;
PLUS Great discounts on RoboHelp training. OFFER EXPIRES April 30th! 
Call 1-800-358-9370 or visit: http://www.ehelp.com/techwr-l

---
You are currently subscribed to techwr-l as:
archiver -at- techwr-l -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.