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.
Subject:Re: "dummy" books to... From:Len Olszewski <saslpo -at- UNX -dot- SAS -dot- COM> Date:Tue, 29 Mar 1994 13:12:10 -0500
Mike Pope talks about defining new terms:
> Well, our style is that a new term has to be defined right where it first
> appears. We don't happen to use marginalia for that, but that seems
> reasonable. Then every term so defined also appears in the glossary at the
> end. My feeling is that the definition tends to be more meaningful in
> context, but if you're far from the original definition when you encounter a
> strange term, the glossary'll do ya.
This matches what we do here, too. In fact, the first occurrence
definition is one of the few places we still use italics. We italicize
the first occurrence of emphasize the new term to emphasize it. You are
supposed to know *that* from reading our "Using this book" sections,
where the explanations for all the "convention stuff" happens.
BTW, we are thinking of killing our "using this book" sections since we
don't think anybody reads them, and we want to "downsize" our
documentation. Anybody else doing this (i.e. - downsizing in general,
burning your UTB or any other sections you don't think your customers
We streamlined our font usage a couple of years ago, and guess what?
Nobody complained. I imagine that's because nobody noticed. I suspect
the same story will repeat itself when the UTB's bite the dust. But I
I'm not sure whether we'll explain that an italicized term is a first
occurrence for a new definition someplace else in the book, or just
trust that the customers will be smart enough to dope it out on their
own. I hope we go with the latter strategy.
We don't use italics in our regular glossaries, just in case you were
I'm not sure *where* we're going to explain our syntax conventions when
the UTB's disappear. Maybe we'll keep UTB's in reference books.
Hey, what about those Blue Devils?
|Len Olszewski, Technical Writer |"I may be banal, but I'm not |
|saslpo -at- unx -dot- sas -dot- com|Cary, NC, USA| juvenile." - Yours Truly |
| Opinions this ludicrous are mine. Reasonable opinions will cost you.|