RE: [wsrp-wsia] feedback on WSRP 0.8

[Carsten Leue <CLEUE@de.ibm.com>]

Eilon - I remember it as Rich does: when the data structures were not
defined before the operations people found the description of the operation
hard to read because they had to switch pages.
Describing the data structure without giving the details will likely
introduce redundancy.


Best regards
Carsten Leue

-------
Dr. Carsten Leue
Dept.8288, IBM Laboratory Böblingen , Germany
Tel.: +49-7031-16-4603, Fax: +49-7031-16-4401



                                                                           
             Eilon Reshef                                                  
             <eilon.reshef@web                                             
             collage.com>                                               To 
                                       wsrp-wsia@lists.oasis-open.org      
             11/01/2002 08:02                                           cc 
             PM                                                            
                                                                   Subject 
                                       RE: [wsrp-wsia] feedback on WSRP    
                                       0.8                                 
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           
                                                                           




Rich,

I would like to second Alejandro's comment below.

I think it's worth the time to consider how to present the operations
and the structures. One option is to present the operations first and
refer to the data structures below (e.g., provide a concise description
of what a structure *is* without the details). Another option is to
introduce the data structures at first use (and possibly refer to that
first use in other places). I think either way, and potentially better
options that the editors will come up with, will improve the readability
of the document.

My two cents,
Eilon

---

General Comments
-----------------------------------------------------------------------
The spec dives into defining many of the structures without any
functional explanation of their use, kind of a Javadoc. It would help if
we start with the functional description of a operation and then we go
in detail about the data structures the operation uses.

Undefined concepts are used to define new concepts.

<rt>
People had found it difficult to discuss the operations without the data
structures being known. It also didn't work to intertwine the
introduction of data structures with the operation's description. The
best we have so far is this reference like data structure definition
followed by operational descriptions. </rt>



----------------------------------------------------------------
To subscribe or unsubscribe from this elist use the subscription
manager: <http://lists.oasis-open.org/ob/adm.pl>