RE: Calrification from the Editor - Duane Nickull

["COOPER,STEPHENIE (HP-PaloAlto,ex1)" <stephenie_cooper@hp.com>]

Speaking as a technical person, it does not matter whether or not Marketing
and Awareness does a separate write-up.  The fact is that a document should
be readable and as self-contained as possible.  Even a technical audience
should be provided with an overview.

The writers and readers may not be operating at the same knowledge level.
In fact, the technical person reading the document may still be green on the
technology (as I often am).  It's frustrating to me when I'm given a
technical document to read that assumes a certain knowledge level and
doesn't tell me enough for me to figure out where else I ought to be
looking.  It's also frustrating to me if a document refers me to another
source for the overview 1) because now I've yet another place I've got to
look and 2) it's amazing how often I find that the other resource doesn't
exist or doesn't cover what the referring source said it was supposed to
cover.

The writers and readers may not be operating on the same assumptions.  All
assumptions should be expressed in the front matter of a document.

Pardon me if I sound preachy.  I know I could express this more gently but
I'm rather tired right now.

Some references:

http://www.wpc-edi.com/AuthHelp.htm
http://techwriting.about.com/careers/techwriting/library/weekly/aa090299.htm
http://www.nas.nasa.gov/Groups/TechPubs/style.html
http://www.wisc.edu/writing/Handbook/DocAPA.html

Regards,
Steph.

-----Original Message-----
From: William J. Kammerer [mailto:wkammerer@foresightcorp.com]
Sent: Tuesday, May 30, 2000 3:04 PM
To: ebXML List; ebXML Architecture
Cc: ebXML Awareness Team
Subject: Re: Calrification from the Editor - Duane Nickull


Duane Nickull, ed. of Architecture, wrote: "This Technical Architecture
Specification is not meant for a casual reader as much as it is for the
technical audience.  The Education, Marketing and Awareness Project Team
will write a more abstract level document, specifically geared towards
outsiders, that will explain the workings of ebXML for that audience."

Duane:

I don't think we in the Marketing, Awareness, and Education Project Team
will be writing any such document, abstract or not.  Unless I missed
something in all of our meetings - which is possible, since I fall
asleep a lot.

We're geared up only for the most bird's-eye view stuff re: ebXML, such
as FAQs, press releases, 20 second elevator pitches, and giving half
hour presentations.  We will not be editing the specifications coming
out of the other technical groups, except perhaps to lend a hand, if
asked, to give each document a common look-and-feel. We (MAE) would not
be any more likely to write heavily technical specifications than DISA
would write X12 manual prose - that's up to the volunteers in the
technical subcommittees to do.

I have already indicated that I have had some trouble understanding the
document and discerning the architecture.  I may be somewhat slow and
plodding, but I am not a casual reader.

William J. Kammerer
FORESIGHT Corp.
4950 Blazer Memorial Pkwy.
Dublin, OH USA 43017-3305
(614) 791-1600

Visit FORESIGHT Corp. at http://www.foresightcorp.com/
"Commerce for a New World"


=======================================================================
= This is ebXML, the general mailing list for the ebXML committee     =
= The owner of this list is owner-ebxml@oasis-open.org                =
=                                                                     =
= To unsubscribe, send mail to majordomo@lists.oasis-open.org with    =
= the following in the body of the message:                           =
=      unsubscribe ebxml                                              =
= If you are subscribed using a different email address, put the      =
= address you subscribed with at the end of the line; e.g.            =
=      unsubscribe ebxml myname@company.com                           =
=======================================================================