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/

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.).

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

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.

5. s/As with any other extension, it can be used/As with any other 
extension, it can ONLY be used/

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

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

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/

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.

15. s/if you wish/if one wishes/ (to be in pair with the overal tone)

16. s/Please note when/Note that when/

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.)

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

19. s/Hopefully, these MEPs will cover/The MEPs should cover/

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]

22. s/More MEPs/Additional MEPs/

23. s/No fault maybe/No fault can be/

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

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

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

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

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

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

30. s/by integration infrastructure/by the underlying infrastructure/

31. s/infrastructure. For example/infrastructure.<new-line>For example,/

32. "logInquiry". Change font to distinguish from surrounding text.

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:/

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.

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)".

38. Section 7.2.1. This should first mention what a SOAP module is.

39. "securityLevel". Change font.

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

41. "wsdl:service". Missing <el>.

42. "but you SHOULD anticipate". Lowercase should.

43. "The draft finding on Versioning and Extensibility details". Repeat 
reference to the finding.

44. "CheckAvailability". Font.

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

46. "checkAvailabilityResponse". Font.

47. s/a service may choose to allow/a service may prefer to allow/

48. "required=�?true�?". Font encoding issue. [several occurences]

49. s/directly in the Body/directly in the SOAP Body/

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.

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/

55. s/ it should contain URIs/ it should only contain URIs/

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/primer-todo.htm_ 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/primer-todo.htm> 
>
> [2] 
> _http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20-primer.html_ 
> <http://dev.w3.org/cvsweb/%7Echeckout%7E/2002/ws/desc/wsdl20/wsdl20-primer.html> 
>
>
> Best Regards,
> Kevin
>  
>

Received on Tuesday, 3 May 2005 11:15:44 UTC