Re: "Two-track" documentation?

[Arlen -dot- P -dot- Walker -at- jci -dot- com]

Andrew's advice, makes a few assumptions, as usual.

1) There's only one kind of technical writing. This is, like all
generalizations, suspect (and this one is no exception). The need for
clarity and conciseness is needed always, but the definition of these terms
will vary with the audience. What is a model of clarity to an engineer will
be incomprehensible to Mrs. Johnson's 3rd grade class. (Yes, I picked an
extreme example. I did so for clarity's sake. The differences will still
exist between other audience sets, but not quite as markedly.)

2) There's always enough space to write for beginners, even when covering
material of a high level of complexity.  Truth is, there are often resource
constraints. Sometimes the constraints are physical (if a book on chaos
theory were to include usefule explanations every piece of mathematics
required to take a neophyte up to expert level, the book would be too large
to be of practical use to anyone) and sometimes there are political (we
don't want to include basic math functions in the work, because we don't
want to deal with customers who don't have a solid grounding in statistical
analysis.). These decisions are sometimes wise and sometimes foolish, but
rarely are they within the purview of the writer to make.

Final nit, only on-topic in so far as clarity and accuracy and a thorough
understanding of the concept are of interest to tech writers.

>"Purist" I love that term.  It immediately conjures in my mind a gang of
>stone-faced Puritans standing around a foggy, gray swamp in winter
preparing to
>dunk a woman in the water to test if she is a witch. "If she drowns, she's
a
>true technical writer."

Anyone who considers this image to be a typical puritan image needs to do a
little more reading in history. A couple of other tidbits about the
Puritans, for those interested:

1) A large number of the founding members of Britain's Royal Society were
puritans, and they contributed a lot of fundamental material to the body of
scientific knowledge.

2) It was a Puritan custom that those graduating from college should be
supplied with free beer for the celebration.

(Were the puritans perfect? No. But they were, on the whole, quite a bit
different from the popular conception of them today. Do a little research
on their customs and behaviors; I guarantee you'll be surprised, and you
might end up enjoying it. They make a good case study in the propagandist's
art of turning caricature into accepted reality.)


Have fun,
Arlen
Chief Managing Director In Charge, Department of Redundancy Department
DNRC 224

Arlen -dot- P -dot- Walker -at- JCI -dot- Com
----------------------------------------------
In God we trust; all others must provide data.
----------------------------------------------
Opinions expressed are mine and mine alone.
If JCI had an opinion on this, they'd hire someone else to deliver it.