Re: A few fixes

[Mary McRae <mary.mcrae@oasis-open.org>]

For some reason this paper isn't being discussed on the TC list; any  
discussion with regard to the document must happen there. Once again,  
this template is not to be used for this document; the only approved  
document template for TC work is the specification template.







On Jul 27, 2009, at 1:36 PM, Waters, Jeff CIV SPAWAR SSC PAC, 53621  
wrote:

> Hi, All:
>
>  I like the looks of this format very much.  Thanks to Rex and  
> everyone for making this paper so nice.
>
> I fixed a few items (see attached document with changes recorded),  
> but perhaps to an earlier Friday version than Rex's latest, sorry.   
> I've listed the primary ones below.
>
> (1) The iso 639 code link was broken, so I revised it.
> (2) Figure 1 needed to be moved down two paragraphs and the  
> reference to it moved accordingly, in order for the current text to  
> make sense.
> (3) The "DE Distribution Tags" subheading was lost, it was appearing  
> as just regular text, so I fixed that.
> (4) (There is still a formatting problem with pages 11/12, which I  
> didn't fix.)
> (5) Some of the http://... links were not links, so I made them links.
> (6) This version still has the DE schema in Appendix A, which I  
> prefer. I agree with Mary that normally and traditionally and from a  
> data management view, one would just link to the schema; however,  
> for adoption and educational purposes especially from a printout  
> that one could read on a train or wherever, it's useful to have it  
> with the paper.   I also was making another point by including it as  
> Appendix A.  The point is that the DE is simple, it's only 3 pages,  
> and in fact, it's so simple I can include it as an Appendix right  
> here for the reader's convenience in a printout. I also liked the  
> idea of handing the paper to someone and having it be complete and  
> stand-alone. The power of being able to hold something in your hand  
> is still valuable. When I show the paper to someone, I will flip to  
> the back and point at things. It's useful to have the schema there  
> in the printout for these instantaneous educational and tutorial  
> purposes without having to take the time to go look it up.  So my  
> preference would be to leave it in. My suggestion is that we have  
> both an official link (that won't change) to the schema referenced  
> in the paper, but also include the schema in the Appendix as an  
> unofficial convenience. (When a new version of the schema comes out,  
> a new version of the paper will also need to come out, and there  
> will be no confusion which schema the old paper was referencing  
> because it's right there in the Appendix.)
>
> --Jeff
> 619-208-3018
>
> ________________________________
>
> From: Rex Brooks [mailto:rexb@starbourne.com]
> Sent: Sat 7/25/2009 9:31 AM
> To: Waters, Jeff CIV SPAWAR SSC PAC, 53621
> Cc: Dee Schur; carol.geyer@oasis-open.org; mary.mcrae@oasis- 
> open.org; dellis@sandia.gov
> Subject: Re:
>
>
>
> Thanks Jeff, Hi Dee, Carol, Mary, Dave,
>
> I deleted the old stylesheet which was a mix of the stylesheet you  
> have
> on your machine, Jeff,  and selections from the OASIS Specification
> Template which I originally advised, and replaced it with the OASIS
> Specification Template and adjusted the styling throughout, which
> brought the total number pages down from 18 to 14. I put the two
> Figures, the Schema and Example into the "code" format which I think
> sets it off better.
>
> Carol, Dee, Mary, this is not a White Paper per se even though it
> addresses some of the things a White Paper does. I am putting it into
> the White Paper Template, too, and I will send it to you when I'm  
> done.
> However, we want to get the feedback process started and we need to be
> clear that our approach doesn't fall neatly into a White Paper  
> category.
> We also want to get this out as soon as we can, with the caveats I
> suggest at the end of this too-long message.
>
> Background: We are in the midst of defining a set of document and
> documentation types plotted against target vendor and governmental
> audiences for each specification at beginning, intermediate, and
> advanced levels. Further differentiations are being worked for
> non-technical managers, technical staff, and decision makers, and  
> there
> will be further refinements.
>
> In the EM Adoption TC's Collateral and Documents SC, which I'm  
> chairing,
> we are developing a spreadsheet that plots document types against
> audience types, so that we can keep track of our thinking and create  
> the
> framework for documenting our progress and providing accountability.  
> We
> want to learn from our experience in a structured way.
>
> We are coordinating with the EDXL-RIM (Reference Information Model) SC
> for its immediate need for a similar Basic or Welcome document, as  
> well
> as the next level up, an intermediate technical audience.
>
> We think each of these audience groups need to be addressed in  
> different
> ways for different purposes. Needless to say, we are only at the
> beginning, and this is the first time we've done this, so we wanted to
> get to a point where it makes sense to ask you for your feedback, and
> that is what we need from you as soon as you can get to it.
>
> We actually have enough people working on these projects to make  
> decent
> progress. What I think we need to do is to develop an identifiable  
> look
> and feel for the format and a tone for the writing for each of these
> levels and avoid the kitchen-sink syndrome where we try to address all
> audiences at all levels simultaneously. Of course, then the task  
> will be
> to get the appropriate documents to the correct audience.
>
> As I said, I am putting this document into the White Paper format so
> that we can compare and think about the distinctions we want to  
> make. I
> really like the White Paper format as a former art director-designer,
> but I worry that a technical audience might not know what to do with  
> it,
> e.g. how to interpret it, as in "Is this addressed to me?"
>
> Dave, Jeff has cast the issue of the lack of complete DE-aware
> distribution in the last sentence of the first paragraph of Section 6:
> "There are a number of current distribution mechanisms available while
> fully DE-aware solutions are emerging." Remember, we are trying to  
> focus
> on what can be done now and staying as positive as we can. Making
> negative statements like, "Fully DE-aware solutions are not yet
> available," will tend to discourage rather than encourage our  
> audience.
>
> Further, in the last paragraph, Jeff writes: "Of course, these options
> are only the beginning..." and while I don't want to lead our audience
> into thinking they can achieve everything in the DE now, we have to
> build adoption and demand for that now.
>
> However, having said that, I think we really need to get a second,
> intermediate level document underway soon, perhaps working with Gary  
> Ham
> and DM OPEN. At the same time we should make sure that DM OPEN is  
> clear
> with anyone we channel to them that this whole system is being
> overhauled and full implementation efforts should be coordinated with
> their timeline. Otherwise, everyone we send their way will come away
> with a really bad impression when that system is changed in such a way
> that it will not be backward compatible, and that is exactly what
> they're doing.
>
> We have to very careful with this.
>
> Cheers,
> Rex
>
> Waters, Jeff CIV SPAWAR SSC PAC, 53621 wrote:
>> Hi, Rex:
>>
>>  Sorry this took me awhile to send to you.  I didn't yet join the  
>> infrastructure subcommittee, so perhaps you could upload these  
>> documents to the resources folder for me. Also I wanted to give you  
>> another chance to look at the changes I made to last paragraph of  
>> Section 6 before uploading. If you don't agree with what I did,  
>> please change back to wording you used or otherwise as you see fit.
>>
>>  I'm cc'ing Dee, so she'll know that basically (after your review  
>> and upload), it may be ready to vote this draft out of the  
>> infrastructure subcommittee. Thanks.
>>
>> --Jeff
>>
>> P.S. I wanted to revise the last paragraph of Section 6 to ensure  
>> we include Dave's concern that people realize that routing  
>> solutions which will take full advantage of the DE have yet to be  
>> developed. I tried to say this in a positive way. Also I wanted to  
>> note that additional papers explaining EDXL will be forthcoming,  
>> but to do so in a positive way without implying that people need to  
>> wait before proceeding to adopt.  I added your wording to the excel  
>> spreadsheet and also the wording I revised and why.  On the other  
>> hand, if you don't like what I did, you can change back.
>>
>> Your wording was:
>>
>> "Please be aware that this is a basic introduction to a necessarily  
>> technical topic and is aimed at an audience with a managerial level  
>> understanding of the technical issues involved. It is not intended  
>> to be a comprehensive technical manual. An intermediate technical  
>> level paper is planned to which managers can refer their technical  
>> staff  for guidance in getting started on implementing EDXL-DE in  
>> order to distribute the various emergency communications message  
>> payloadss for which EDXL-DE is intended."
>>
>> My thoughts and revision:
>>
>> I may be wrong, but I'm not sure this paragraph is necessary. The  
>> title and many parts of paper refer to this as a "basic" intro, and  
>> I think it's clear that it is not a comprehensive technical manual.  
>> Although basic, I'm not sure I agree that it is directed toward  
>> managers, since I don't think managers are interested in the xml  
>> examples. Also I'm afraid this paragraph might suggest to readers  
>> that they should wait until the next paper comes out before  
>> proceeding.  It is important to note that the routing solutions  
>> proposed are not complete and don't take full advantage of the DE.  
>> Also important to note that other explanatory papers are in the  
>> offing. So suggest revising to rephrase main points in a more  
>> positive light.  Section 6 last paragraph to read: "Of course,  
>> these options are only the beginning. New routing solutions and  
>> architectures are needed to take full advantage of the DE. Now is a  
>> good time to consider joining OASIS so your company or organization  
>> can assist in these efforts." Also added this line to the end of  
>> 1st paragraph of Section 7 Conclusion: "Additional papers  
>> explaining the details of the EDXL standards are underway."
>>
>
>
> --
> Rex Brooks
> President, CEO
> Starbourne Communications Design
> GeoAddress: 1361-A Addison
> Berkeley, CA 94702
> Tel: 510-898-0670
>
>
>
> <EDXL-DE-Basics-WD05[1]-JeffFixes.doc>