RE: "Two-track" documentation?

Subject: RE: "Two-track" documentation?
From: kimber_miller -at- acs-inc -dot- com
To: <techwr-l -at- lists -dot- raycomm -dot- com>
Date: Tue, 14 Dec 1999 12:47:44 -0600

Catherine Strauss wrote, in part:
>"My question is: What constitutes an audience?
>Do people of three distinct skill levels constitute one audience, or three?
>What if the skill levels are more varied, and could be subdivided into 7
>different categories, from my grandmother (who just bought her first
>computer), to my mother (who works in web page design), to a friend who is,
in fact, a rocket scientist? "

[Kimber remarked:] My thoughts on this thread's turn:
The poster who originated this topic (sorry, deleted original days ago) wanted
to know how in the world to organize a document so that ONE audience at TWO
disparate skill levels could best obtain information.

We have digressed from the original question, but Catherine brings the circle
back to the first point. The "audience" is whoever picks up the book, clicks on
the link, or opens the Help file. In the strictest terms, we have no real clue
who our audience will *actually* be. We give it our best professional hypothesis
that our audience will have certain needs for certain types of information, and
we go from there.

Where we "go" is toward an end product that is as useful (readable, accurate,
and organized) as possible for the audience of our hypothesis. Even if we're not
allowed the time or budget to exhaust audience/user analysis possibilities, we
have some innate assumption, once we look at the thing, what people want/need to
know about it.

Now, as to the *original* question. (I hope the original poster is still reading
this wandering thread) :

A long, long time ago, in a start-up far, far away, I wrote a manual for a new
I-net firewall product. Multi-protocol filtering was novel at the time and the
product was expensive. Non-geek managers and hard-core geeks were the levels for
which I had to write the ONE manual.

So, I produced a Concepts Guide that was outside the realm of the User Manual
(and which could be used for pre-Sales purposes). The name is self-explanatory,
but it was small and contained the underlying concepts of firewalls, network
security, security holes, and the reasons people used more than one protocol on
the I-net. I persuaded my boss that these basic concepts were not actually part
of -using- the firewall and thus should not be included in the Guide, but
offered in support of novice users and the managers who had to sign the P. O.

In organizing the User Guide, I identified some tasks as rudimentary to using
the product, some as advanced uses of the product, and some as "developer only"
tasks (like writing original filters for proprietary protocols). In the body, I
gave the necessary background and procedures for the basic tasks. In shaded
boxes, I gave "advanced" tips, pointers, and alternatives. I used a bulleted
header for "Advanced Procedures" that were similar to the basic one, but not
always implemented at the firewall's first installation. To introduce any of
the advanced procedures, I used the same bulleted header: "% For Advanced
Security... " By doing it this way, I could group the basic and advanced
techniques, yet clearly separate them.

For the Developer Tasks, I created a separate section of the manual,
"Developers' Security Solutions." It was available in the TOC and anybody could
read it. But I assumed that the technical level of my targeted audience for that
section would be above average, so it was more segregated than the "advanced"

This is difficult to visualize in an email. In fact, re-reading this, it sounds
like crap. But in the physical layout it worked well (promise!). Even merited a
mention by some reviewer in some PC magazine.

I hope this helps answer the original question, which had naught to do with
which was more important, audience or information. <sigh>

Enjoy the day,



Kimber Miller
Affiliated Computer Services
Dallas, Texas

Little minds are interested in the extraordinary; great minds in the
commonplace. --Elbert Hubbard

Previous by Author: Font Weirdness--Thank you, that's enough
Next by Author: OT--Question for Home Office Networking
Previous by Thread: Re: "Two-track" documentation?
Next by Thread: Explaining buttons without using graphics

What this post helpful? Share it with friends and colleagues:

Sponsored Ads

Sponsored Ads