Re: "dummy" books to...

[Len Olszewski <saslpo -at- UNX -dot- SAS -dot- COM>]

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
really need...)?

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
digress...

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
wondering.

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