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: 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:Dan Goldstein <DGoldstein -at- cytomedix -dot- com> To:"TECHWR-L (techwr-l -at- lists -dot- techwr-l -dot- com)" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Thu, 19 Dec 2013 14:45:34 -0500
Personally, I'd focus on doing a fast, high-quality job on the first task they give me, only offering corrections for actual errors. Once you impress them with your speed and talent, they might be more open to discussing this sort of improvement on your next task.
In other words: First show them the value, and then show them the value added.
-----Original Message-----
From: Elissa K. Miller
Sent: Thursday, December 19, 2013 11:44 AM
To: techwrl
Subject: On the value of glossaries containing terms the audience should already know
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.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
