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:"rebecca officer" <rebecca -dot- officer -at- alliedtelesis -dot- co -dot- nz> To:"Robert Lauriston" <robert -at- lauriston -dot- com>, "TECHWR-L (techwr-l -at- lists -dot- techwr-l -dot- com)" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Tue, 07 Jan 2014 12:15:53 +1300
I also think it's important to think about what your knowledgeable users might need from a glossary entry. They'll know you mean Internet Protocol, but they may want to know whether that includes IPv6 or is only IPv4.
We make network switches, and we single-source a glossary across the whole product range. The product range varies from beginner right up to expert-only gear. No expert's ever complained about the glossary including terms like DNS.
I also do some administration of our company's patent portfolio. Sometimes I have to think a moment to figure out what someone means by IP!
Cheers
Rebecca
>>> Robert Lauriston <robert -at- lauriston -dot- com> 21/12/13 12:46 >>>
Elissa said, "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," which might mean she's got a similar audience.
For example, if I were documenting a command-line interface for a
piece of hardware that lives in an equipment closet, such as a big
router or network switch, I would never waste time and space defining
DNS or IP. You don't have a key to the closet if you don't know a lot
more than that. If you're some clueless user dealing with an
emergency, you need to call tech support and have them guide you.
On Fri, Dec 20, 2013 at 2:44 PM, Fred Ridder <docudoc -at- hotmail -dot- com> wrote:
> Robert Lauriston wrote:
>
>> When you're documenting a mission-critical product that's used only in
>> secure environments with hundreds or thousands of servers, you don't
>> have to worry about that.
>>
>> On Fri, Dec 20, 2013 at 1:29 PM, Gene Kim-Eng <techwr -at- genek -dot- com> wrote:
>> > I've been in more than a few start-ups where some newly hired clerical
>> > employee was handed a network manual and told that he or she was now the
>> > company's sysadmin.
>
> But that is going to be the case for how many list members? Pronouncements that only apply to one in a hundred members are not very helpful to the other 99. Most of us work in the real world where pointy-haired bosses are all too common.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
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
NOTICE: This message contains privileged and confidential
information intended only for the use of the addressee
named above. If you are not the intended recipient of
this message you are hereby notified that you must not
disseminate, copy or take any action in reliance on it.
If you have received this message in error please
notify Allied Telesis Labs Ltd immediately.
Any views expressed in this message are those of the
individual sender, except where the sender has the
authority to issue and specifically states them to
be the views of Allied Telesis Labs.
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
New! Doc-to-Help 2013 features the industry's first HTML5 editor for authoring.
