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

Re: Primer feedback

From: David Booth <dbooth@w3.org>
Date: Thu, 04 Nov 2004 09:50:02 -0500
To: Jean-Jacques Moreau <jean-jacques.moreau@crf.canon.fr>
Cc: www-ws-desc@w3.org, Kevin <kevin.liu@sap.com>
Message-Id: <1099579802.3419.219.camel@nc6000.w3.org>

Jean-Jacques,

Thanks very much for your feedback.  It is very helpful.  Some comments
are inline below.

On Wed, 2004-11-03 at 07:05, Jean-Jacques Moreau wrote:
> This is great and very enjoyable up to (and including) section 2.2.

Great!  I guess we're on the right track then.

> Section 2.3 suddenly drops the very nice step-by-step approach and 
> presents al the topics in one go. 

Hmm, the intent was to give a brief "big picture" view of what we'd be
covering, but perhaps it's too much here.  I'd be concerned about not
having *any* big-picture overview though.  I'll try reducing it, and see
if it still looks like too much.  Another possibility might be to move
it to the intro section, which discusses the content of the primer as a
whole.

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

Hmm, that's an interesting idea.  So essentially you're suggesting that
the order of presentation be driven by the designer's thought process in
designing the WSDL, rather than being driven by the sequence of reading
through the example WSDL itself.  Ok, I'll give that a try and see how
it looks.


-- 

David Booth
W3C Fellow / Hewlett-Packard
Received on Thursday, 4 November 2004 14:50:04 GMT

This archive was generated by hypermail 2.2.0+W3C-0.50 : Monday, 7 December 2009 10:58:33 GMT