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.
RE: [BULK] Re: On the value of glossaries containing terms the audience should already know
Subject:RE: [BULK] Re: On the value of glossaries containing terms the audience should already know From:"McLauchlan, Kevin" <Kevin -dot- McLauchlan -at- safenet-inc -dot- com> To:Mike McCallister <mike -dot- mccallister -at- pkware -dot- com>, Julie Stickler <jstickler -at- gmail -dot- com>, "Elissa K. Miller" <emiller -at- doubleknot -dot- com> Date:Fri, 20 Dec 2013 10:26:52 -0500
Context is everything. My first encounters with -isms like that are usually a bother.
The "intellectual property" = "IP" thing started becoming popular (er.... sorry.... I meant "started gaining traction") years ago, but when I first met it, it took me a bit of cogitating to figure out what they were saying, as opposed to what they were.... saying. When that happens, I often miss the next few paragraphs of what the suit is saying, while I shift paradigms.
So maybe what WE are saying here is that it would be beneficial to have a glossary that included [some of] those other definitions of terms and acronyms that are used one way in the technical segments of our industry, for technical audiences, but might be encountered elsewhere (or even from our own corporate suits) with different meanings. We'd need a convention (maybe just the first definition of each term would be indication enough) which of the flavors was intended for the current document. After all, we can never really know from what background our audience is coming. Maybe a biz-development guy is trying to use our docs as a sales tool and is therefore actually (gasp!) reading some of 'em... and wondering why we keep referring to 'intellectual property' in this section about remote backup over networks.
-----Original Message-----
From: Mike McCallister
Subject: RE: [BULK] Re: On the value of glossaries containing terms the audience should already know
...and depending on the context, IP can also be "intellectual property." I've been thrown by that when our CEO or marketing people toss it around. "Why do we want to protect our Internet Protocol? Is it broken?"
As always, never assume...
Mike
-----Original Message-----
From: Julie Stickler
Subject: [BULK] Re: On the value of glossaries containing terms the audience should already know
Importance: Low
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
>
>
The information contained in this electronic mail transmission
may be privileged and confidential, and therefore, protected
from disclosure. If you have received this communication in
error, please notify us immediately by replying to this
message and deleting it from your computer without copying
or disclosing it.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
