SUMMARY & LONG: You're too stupid for this document?

[Darren Barefoot <dbarefoot -at- mpsbc -dot- com>]

Good morning,

Earlier this week I asked:

>"We write quite a few technical bulletins, some of each are directed at
system administrators and other advaced users. Does >anybody have some
standard boilerplate text that gently and effectively articulates the
intended audience for a document?"

>"To understand and implement the procedures outlined in this article, you
should have an intermediate to advanced knowledge >of MicroBlatt TreeMulcher
2000."

>We also tend to set off this sort of information in the left margin of the
first page of the bulletin. Still, I'm finding it >somewhat unsatisfactory.
Any tips regarding articulating the intended audience would be much
appreciated.

Thanks very much to everyone who responded. I'll take it all into
consideration and devise an effective message. The responses are below. DB.

****

Alyssa Fox:

We use something along the lines of:

"This guide is intended for System Administrators and Operators who will be
involved in configuring and maintaining Plot Express Manager. This guide
assumes that the person using the software is an experienced UNIX or Windows
NT user and has access to a text editor."

****

Dan Roberts:

i dont like "understand and implement"--sounds a bit condescending? maybe
that's just my take on it.

perhaps..."To [use] the procedures outlined in this article, you should [be
experienced with using] MicroBlatt TreeMulcher 2000 [to blatt micros, mulch
trees, and recompost heaps]."

in other words, perhaps state the general area or procedures that the
bulletins provide additional information about. Or perhaps, if the bulletin
procedures require certain authorizations, state that condition.
perhaps..."To [use] the procedures outlined in this article, you should [be
authorized to design and implement heaps of compost]."

****

DowningLst -at- aol -dot- com:

I'd say something like, "This document assumes the following knowledge."  I
think that's nice and polite because it implies that the writer of the
document is the one who's made the mistake if the document goes over the
reader's head -- "We assumed, but we assumed wrong."

****

Elna Tymes:

Many Sun manuals have a standard preface that includes a section on "Who
Should Use This Book."  The wording is something like this: "The
MasterBlaster Sunscreen Protection Kit Guide is intended for the system
administrator whose duties include applying and monitoring sunscreen on
children under 10.  Familiarity with basic containment procedures and with
the warning signals of sunburn and heat exhaustion are helpful."

****

Jean Ostrem:

You might consider something a little more direct: "News of interest 
to system administrators and expert users of MicroBlatt TreeMulcher 
2000."

This still will only turn away the novice users who are actually 
paying attention, which is probably the problem to begin with.

****

Jennifer Banks:

Our Programmer's Guide has a short introductory chapter describing the
manual and its intended audience.  The audience info reads as follows:

  This Programmer's Guide is written for experienced software developers
  who have a working knowledge of the C and C++ languages and the specific
  processor being targeted.

The passive voice is less than optimal, but it sidesteps the issue of
how you tell people they aren't smart enough to read your manual.

****

Lisa Wright:

Is this a document such that you could use a subtitle to your bulletin title
(I Know there's a word for that but it's late and I'll be darned if I'm
looking it up right now)? e.g., "TechBull: The technical bulletin for
advanced TreeMulchers" If you have a pub info/contact section, you could do
a "TechBull is published for users with advanced knowledge of TreeMulching"
blurb.

You don't talk about your distribution method, but if you use email, I've
seen things like "You are receiving this email because you are an advanced
Mulcher. If you feel you have received this message in error, please contact
Jane Smith at..."

Can you filter who receives the communication? Also, even if they receive it
and aren't smart enough to know what to do with it, do they have access to
try? If the only ones who can do any damage are the SAs, you might not have
too much to worry about.

****

Al Rubottom:

"This document is intended for [advanced/expert] users of Microfroth
BrainBuzz. Familiarity with {you-name-it} is assumed for ease of
discussion."

New users [or whatever euphemism appeals--novice?] should refer to Clueless
Newbie Guide, xyz-123.

****

Tom Murrell:

I think it makes sense to day "to understand the procedures outlined in this
article..." but I'm not sure that is sufficient for the implementation of
those procedures, as your blurb says.

Wouldn't you need something in addition to implement the procedures?  I'm
thinking you would need administrative permissions or access to the
TreeMulcher admin directory or some such?

"To understand the procedures outlined in this article, you should have an
intermediate to advanced knowledge of MicroBlatt TreeMulcher 2000.  To
implement these procedures, you also need administrative permissions and the
special KAZAM! directory password."

****

Darren Barefoot 
Meridian Project Systems 
Manager of Documentation
604-904-0822 ext. 112 
dbarefoot -at- mpsbc -dot- com 
www.mps.com 

I have made this letter longer than usual, only because I have not had the
time to make it shorter. - Blaise Pascal