Subject: RE: Calrification from the Editor - Duane Nickull
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-awareness, the general mailing list for the ebXML = = Marketing and Awareness project team. The owner of this list is = = owner-ebxml-awareness@oasis-open.org = = = = To unsubscribe, send mail to majordomo@lists.oasis-open.org with = = the following in the body of the message: = = unsubscribe ebxml-awareness = = 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-awareness myname@company.com = =======================================================================
Powered by
eList eXpress LLC