RE: Primer draft ready for review

Hi Jean-Jacques,

I have incoprated most of your comments (those marked done below) into the editor's draft of the primer except a few I considered just different writing styles. Please check it out and let me know if I missed anything.


Best Regards,
Kevin
  

> -----Original Message-----
> From: Jean-Jacques Moreau [mailto:jean-jacques.moreau@crf.canon.fr] 
> Sent: Tuesday, May 03, 2005 4:15 AM
> To: Liu, Kevin
> Cc: Jonathan Marsh; Hugo Haas; www-ws-desc@w3.org; David Booth
> Subject: Re: Primer draft ready for review
> 
> Hello,
> 
> Overall, I think this is a great primer. It easily introduces the 
> essential concepts, and then dwelves down at length (pls read 
> this as a 
> compliment) into the more complex issues. On this aspect, it goes 
> further than the XML Schema primer. Congratulations!
> 
> Other comments below.
> 
> JJ.
> 
> --
> Comments on WSDL 2.0 Primer, labelled "Editors' copy $Date: 
> 2005/05/02 
> 02:44:00 $".
> 
> All comments in document read order, except for comment 56.
> 
> 1. s/XML Schema target namespace: interface, binding etc/XML Schema 
> target namespace. Interface, binding etc/
Done
 
> 2. "The value of the WSDL target namespace MUST be an absolute URI. 
> etc". The whole paragraph feels like spec speak. I suggest 
> using a more 
> casual rewrite (and no capital MUST etc.).

Done.

I notice that we are not consistent with the use of MUST/must, SHOULD/should etc throughout the document.
Have replaced all capital MUST, SHOULD with lower case ones as suggested.

> 3. s/WSDL 2.0document/WSDL 2.0 document/

Done

> 4. "The following schema defines checkAvailability etc.". I suggest 
> using a different font for items like checkAvailability, so 
> they stand out from the surrounding text.

Done. Let me know if I missed any.
 
> 5. s/As with any other extension, it can be used/As with any other 
> extension, it can ONLY be used/
Done

> 6. s/by having different labels/by using different labels/
Done

> 7. s/the messageLabel/the <att>messageLabel</att>/
Done

> 8. "In order to accomodate new kinds of message formats etc.". The 
> paragraph continues with a 4 references in 2 neighbouring 
> sentences. The 
> 2 sentences are difficult to parse.

> 9. "It specifies the underlying transmission protocol that should be 
> used, in this case HTTP.". I suggest adding: "(SOAP can be used with 
> multiple underlying protocols.)"
> 
> 10. s/This not defining/This IS not defining/

Done
 
> 11. s/The following is a pseudo-conent model of 
> description/For example, 
> [repeat]/
 
> 12. s/should be ordered as follows:/should be ordered as 
> follows (this 
> is indeed how the WSDL 2.0 specification is structured):/
> 
> 13. "The WSDL 2.0 component model is particularly helpful in defining 
> the meaning of |import| and |include|.". I suggest adding something 
> like: "The resulting specification is simpler, as it only 
> needs to speak 
> in terms of components, irrespective of where these components are 
> actually located (i.e. in which imported or included files.".
> 
> 14. "A WSDL |description| MUST NOT refer to XML Schema 
> components etc.". 
> Suggest removing capital from MUST NOT.
> 
Done

> 15. s/if you wish/if one wishes/ (to be in pair with the overal tone)
Done
 
> 16. s/Please note when/Note that when/
Done
 
> 17. "An optional safety attribute whose value". Add reference to an 
> earlier section that allready mentions the safety attribute. 
> (Or maybe 
> shorten this paragraph alltogether.)
Actually the early section references this section. BTW, this reminds me that "safety" should be replaced with "safe". 

 
> 18. s/is optional: it is not necessary/is optional. It is not 
> necessary/
Done

> 19. s/Hopefully, these MEPs will cover/The MEPs should cover/
Done
> 
> 20. s/use cases, but they are not meant/use cases. They are not meant/
> 
> 21. s/8 MEPs/eight MEPs/ (otherwise clashes with refereces, 
> for example 
>  >>8 WSDL 2.0<< MEPs) [several occurences to fix]
Done
 
> 22. s/More MEPs/Additional MEPs/
> 
> 23. s/No fault maybe/No fault can be/
Done

> 
> 24. s/Depends on how/Depending on how/

Done
 
> 25. s/in-bound MEPs in which case/in-bound MEPs, for which/

Done

> 26. s/out-bound MEPs in which case/out-bound MEPs, for which/

Done
 
> 27. s/Such Grouping is only for/Such grouping is not present 
> in the WSDL 
> 2.0 specification and is only presented here for/
Done


> 28. s/A frequently asked question about out-bound MEPs is how a 
> service/One may wonder how a service/
Done

> 29. s/for abstractly specifying the functionality of a service/for 
> specifying the functionality of a service abstractly/
Done


> 30. s/by integration infrastructure/by the underlying infrastructure/
Done
 
> 31. s/infrastructure. For 
> example/infrastructure.<new-line>For example,/
> 
> 32. "logInquiry". Change font to distinguish from surrounding text.
Done
 
> 33. s/Here are the general steps for defining a new MEP./Here are the 
> steps you should try to follow when defining a new MEP:/

The whole section is subject to change. Added ednote
 
> 34. "|http://greath.example.com/2004/bycheckInDate/5-5-5". Maybe also 
> indicate the content of the HTTP body, so the user understands where 
> ||roomType=foo| disappeared.

 Done


> 35. "From the abstract:[quote follows]". Suggest indenting the quote.
> 
> 36. "two extensibility mechanisms". However, only one has 
> been presented 
> so far. Add a short introduction to F&P and refer to 7.2. 
> Also indicate 
> that open-content model was described earlier (and add a reference).
> 
> 37. "We also assume that a SOAP module". Add: "(see 7.2.1 below)".
Done

> 38. Section 7.2.1. This should first mention what a SOAP module is.
Done. Added ref to soap 1.2 spec in first use of soap module

 
> 39. "securityLevel". Change font.
Done

> 40. "http://hotels.example.com/reservations/wsdl". Missing quotes (in 
> the primer, not on this paragraph).
Changed the font of the uri.

> 41. "wsdl:service". Missing <el>.
?. Changed font for all occurances of wsdl:service
 
> 42. "but you SHOULD anticipate". Lowercase should.
Done

> 
> 43. "The draft finding on Versioning and Extensibility 
> details". Repeat 
> reference to the finding.
> 
> 44. "CheckAvailability". Font.
Done

> 45. "Describing Media Content of Binary Data in XML [ref]." 
> Supply the 
> "ref".
Done

> 46. "checkAvailabilityResponse". Font.
Done

> 47. s/a service may choose to allow/a service may prefer to allow/
> 
> 48. "required=�?true�?". Font encoding issue. [several occurences]
Done

> 49. s/directly in the Body/directly in the SOAP Body/
Done
 
> 50. s/that Dr. Fielding/that Roy Fielding/ (to be consistent 
> with other 
> occurrences of the name)

> 51. "however XPointer can also be used". Add a ref to XPointer.
Done
 
> 52. Noop. I haven't checked the RDF section.
> 
> 53. s/Throughout this document/Throughout this primer,/
> 
> 54. s/the use of a fully qualified URI is simply to/fully 
> qualified URIs 
> were used to simply/
Done
 
> 55. s/ it should contain URIs/ it should only contain URIs/
Done
 
> 56. Section 5.4.1. The text and layout of this section are too 
> reminiscent of that of the spec. I suggest: 1° using 
> paragraphs instead 
> of bullets; 2° using a more casual tone.
> 
> Liu, Kevin wrote:
> 
> > Hi all,
> >
> > I have run another round of editing of the primer, mainly adding 
> > examples, diagrams, and fixing typos and broken 
> > references/placeholders in the document.
> >
> > There are a few remaining to-do items (see [2]) which can 
> be done as 
> > more info is become available. The draft at [2] should be ready for 
> > the group's review.
> >
> > [1] 
> > 
> _http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/prime
> r-todo.htm_ 
> > 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/p
> rimer-todo.htm> 
> >
> > [2] 
> > 
> _http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl2
> 0-primer.html_ 
> > 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/w
> sdl20-primer.html> 
> >
> >
> > Best Regards,
> > Kevin
> >  
> >
> 
> 
>

Received on Friday, 20 May 2005 02:26:14 UTC