Re: "Two-track" documentation?

[Andrew Plato <intrepid_es -at- yahoo -dot- com>]

> I know our Numero Uno Law as technical communicators is "write for
> the audience" and of course, I live by that. 

I always thought the Prime Directive was to write technically accurate
information in a clear and concise manner. Seeing as how we're TECHNICAL
writers and not AUDIENCE writers. 

What do I know? I should go herd llamas.

> Have any of you done this? If so, how did you do it--did you
> separate out the material? Or print the simpler stuff on the left, more
> complex stuff on the right? Or did you just let the reader find their way on
> their own? (I lean toward this last idea, because users seem to select the
> resources that help them and ignore the rest.)

I've written numerous books to dual and triple audiences (and some of them
didn't suck!).  I think all good technical manuals should write to various
levels of readers. The single audience concept is and inane premise that seems
only to provide an excuse to those writers that cannot communicate complex
concepts effectively.

This is not a methodology or a tool issue, this is a simple matter of writing
well. To write to dual audiences you must be able to write about the topic at a
conceptual level and not merely just "pretty up" instructions an engineer
handed to you. 

You also need to be able to organize the material such that conceptual stuff
and detailed stuff follow a logical pattern.  I like to build a hierarchy for
all information.  Start with real simple ideas then slowly progress into more
complex ideas.  Then when you have set the conceptual stage, so to speak, hit
the reader with all the instructions, lists, diagrams, and other "raw" details.

It's like a good novel. Start the reader with the familiar then suck them into
the unfamiliar.

A reader who is advanced will immediately skip over the talk and go for the
details.  Think about it, how many times do you actually read all the text in a
reference manual?  Only when you don't understand the concepts.  If you know
how it all works what do you do?  Skip right over to that table or list that
gives you all the gooey details. 

However, to write this way, you need to be intimately involved with the subject
matter. You must become an expert in whatever you are documenting.  As I have
yelped 1000 times, you cannot write an intelligent document about a subject or
a technology you do not understand yourself. I don't care how many
methodologies or tools you have. 

> To the purists among you, please don't flame me for asking the
> question. I know writing a book like this would break "the rules", but I'm
> trying to think outside the box on this. 

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

A "book like this" breaks no rules except those that you believe to be true. If
you believe there is some Technical Writing Prime Directive - then there is,
for you and you alone. 

I think it is really funny when people talk about how they need to "think out
of the box" at the same time while they tell other people they need to "follow
the rules."  There is a beautiful absurdity in that kind of statements. "Be
creative, but don't change anything!"  I mean, why not tell people to just sit
at their desk all day and play Quake.  It is almost as productive. 

And if you don't see anything absurd with this stuff - then maybe raising
llamas is a more productive career for you.  I hear llamas love methodologies
and rarely "think outside the box". The make funny noises too.

Llama-less
Andrew Plato


__________________________________________________
Do You Yahoo!?
Thousands of Stores.  Millions of Products.  All in one place.
Yahoo! Shopping: http://shopping.yahoo.com