W3C home > Mailing lists > Public > www-ws-desc@w3.org > November 2004

Re: Primer feedback

From: Jean-Jacques Moreau <jean-jacques.moreau@crf.canon.fr>
Date: Wed, 03 Nov 2004 13:05:40 +0100
To: David Booth <dbooth@w3.org>
Cc: www-ws-desc@w3.org, Kevin <kevin.liu@sap.com>
Message-id: <4188C994.60001@crf.canon.fr>

This is great and very enjoyable up to (and including) section 2.2.

Section 2.3 suddenly drops the very nice step-by-step approach and 
presents al the topics in one go. Section 2.4 discusses somewhat boring 
namespaces. Section 2.5 and following start with "types" and gradually 
build-up to higher-level elements.

In order to sustain the reader's interest throughout, I'd suggest the 
following changes:

1) Move sections 2.3 and 2.4 to a later part of the document.

2) Start in section 2.5 with operations. This would provide a better 
link with the introductory sections and the chosen example. Up to that 
point, the reader is primarily interested in the "CheckAvailability" 
operation and how that can be described.

3) Section 2.6 would go from operations to messages, using again 
"CheckAvailability" as an example.

4) Section 2.7 would provide the link with types for the above messages.

5) Section 2.8 would introduce a simple binding for "CheckAvailability".

6) Section 2.9 would add an endpoint for "CheckAvailability".

5) Section 2.10 and following would provide further refinements: 
interfaces, services, faults, MEPs. I feel these additional topics 
should (and can) be avoided in the previous sections, in the interest of 
simplicity and readability. Introducing too many concepts at once is 
always a hard sell.

I hope this helps,


David Booth wrote:

>  In accordance with the WG's previous feedback, Kevin and I have been
>  reworking the primer. It isn't done yet, but we've redrafted enough
>  of the beginning sections that I think you can get a pretty good feel
>  for the new approach. (We've now put an example right up front, and
>  the prose then walks through that example, explaining it.)
>  If other WG members could take a look and tell us what you think I'd
>  appreciate it:
>  http://dev.w3.org/cvsweb/~checkout~/2002/ws/desc/wsdl20/wsdl20-primer.html
Received on Wednesday, 3 November 2004 12:06:21 UTC

This archive was generated by hypermail 2.4.0 : Friday, 17 January 2020 23:06:45 UTC