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

[Haim Roman <haim -dot- roman -at- gmail -dot- com>]

I would think that if you stated your views to your client, and they insist
on leaving these terms in, then you should.  I don't see that it really
hurts.  A glossary is not supposed to be read start-to-finish; the reader
goes there to look up specific words.  I don't think the presence of
obvious terms is going to upset him.

-- Howard (Haim) Roman



On Thu, Dec 19, 2013 at 6:44 PM, 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 haim -dot- roman -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
>


^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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