Re: On the value of glossaries containing terms the audience should already know

Subject: Re: On the value of glossaries containing terms the audience should already know
From: Julie Stickler <jstickler -at- gmail -dot- com>
To: "Elissa K. Miller" <emiller -at- doubleknot -dot- com>
Date: Thu, 19 Dec 2013 14:45:20 -0500

If they EVER plan to translate their documentation, they will need that
glossary to give to their localization vendors. If they want to start
maintaining it now, don't talk them out of it.

Also, just because you know what an acronym means, never assume that your
audience uses the same acronym to mean the same thing. "USB" gets 29 hits
on acronymfinder.com, and SSH has 25.


On Thu, Dec 19, 2013 at 11:44 AM, Elissa K. Miller
<emiller -at- doubleknot -dot- com>wrote:

> Hi, all:
>
>
>
> So, I continue working on an administrative command line reference as a
> freelance gig for a client whose staff consists entirely of engineers-no
> in-house technical writers, trainers, or instructional designers of any
> kind.
>
>
>
> The original document that they created has a glossary that includes a
> section of industry terms and a section of company-specific terms. There
> are
> only five company-specific terms, and even though they're defined in the
> text of the manual, I can see the value of putting them in a glossary as
> well because you might go straight to the command you want to learn about
> and miss the text where it was defined. So, it's a weirdly short glossary,
> but fine.
>
>
>
> But, the industry terms in the glossary are bugging me-they're defining
> really basic terms like RFC, SSH, LDAP, DNS, and IP, and I don't think you
> have any business mucking around with *anything* covered in this guide if
> you don't know what DNS and IP mean.
>
>
>
> Any thoughts on whether it's worth it to argue that it's unnecessary and
> borderline insulting to tell sysops what USB means? (USB is an example
> where
> defining it doesn't even help-my elderly mother knows what a USB port does
> and how to plug things into it without knowing what the acronym stands
> for).
> Does this kind of glossary have any value other than the not-negligible
> value of "leaving it because the client thinks it's important?" This really
> isn't the hill upon which I wish to die in battle, so, "Shut up and format
> the glossary they gave you-no one is going to read the glossary anyway" is
> a
> reasonable response.
>
>
>
> Sorry to have such basic questions, but as I mentioned in my first round of
> basic questions (which included "duuuuh, what do I do with pages and pages
> of sample output?), this is a new world for me.
>
>
>
> Thanks,
>
> Elissa
>
>
>
>
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> New! Doc-to-Help 2013 features the industry's first HTML5 editor for
> authoring.
>
> Learn more: http://bit.ly/ZeOZeQ
>
> ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
>
> You are currently subscribed to TECHWR-L as jstickler -at- gmail -dot- com -dot-
>
> To unsubscribe send a blank email to
> techwr-l-leave -at- lists -dot- techwr-l -dot- com
>
>
> Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
> http://www.techwhirl.com/email-discussion-groups/ for more resources and
> info.
>
> Looking for articles on Technical Communications? Head over to our online
> magazine at http://techwhirl.com
>
> Looking for the archived Techwr-l email discussions? Search our public
> email archives @ http://techwr-l.com/archives
>



--
Julie Stickler
http://heratech.wordpress.com/
Blogging about Agile and technical writing


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.

Learn more: http://bit.ly/ZeOZeQ

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

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications? Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions? Search our public email archives @ http://techwr-l.com/archives


Follow-Ups:

References:
On the value of glossaries containing terms the audience should already know: From: Elissa K. Miller

Previous by Author: Re: Version number question
Next by Author: Re: [BULK] Re: On the value of glossaries containing terms the audience should already know
Previous by Thread: On the value of glossaries containing terms the audience should already know
Next by Thread: RE: [BULK] Re: On the value of glossaries containing terms the audience should already know


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


Sponsored Ads