RE: NEW ISSUE: 3989 [Guidelines] Suggested Format

Asir, 

Instead of arguing about the premise, could you perhaps elaborate on
what you are proposing in detail. 

I am not sure what you are really saying with respect to "hidden"ness of
the guidance, for example. If you could elaborate concretely, it would
help. Are you, for example, suggesting we include a "best practice:" or
"warning:/things to avoid" bullets after each concept in each section? 

I am looking for some more concrete suggestions by taking a single
section and demonstrating it, that would help us move this forward and
understand what you are looking for. 

I am a firm believer of seeing the text you want changed and what it
should be changed to. It is illustrative. A picture is worth a thousand
words. :-)

Thanks, 

--umit



> -----Original Message-----
> From: public-ws-policy-request@w3.org 
> [mailto:public-ws-policy-request@w3.org] On Behalf Of Asir Vedamuthu
> Sent: Thursday, Nov 30, 2006 3:17 PM
> To: Maryann Hondo
> Cc: public-ws-policy@w3.org
> Subject: RE: NEW ISSUE: 3989 [Guidelines] Suggested Format
> 
> 
> >Are you suggesting that the "guidelines" document be renamed 
> to be the 
> >"architecture of policy assertions"?
> 
> No, issue 3989 does not call for changing the name of the Guidelines
> document.
> 
> >I'm assuming this recommendation should also be applied to the primer
> 
> The latest version of the Primer [1] provides an introductory
> description of the features in the Web Services Policy language. The
> Primer does not provide any guidelines.
> 
> [1]
> http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-p
> rimer.html
> ?content-type=text/html;%20charset=utf-8 
> 
> Regards,
>  
> Asir S Vedamuthu
> Microsoft Corporation
> 
> 
> 
> 
> 
> 
> From: Maryann Hondo [mailto:mhondo@us.ibm.com] 
> Sent: Thursday, November 30, 2006 6:17 AM
> To: Asir Vedamuthu
> Cc: public-ws-policy@w3.org; public-ws-policy-request@w3.org
> Subject: Re: NEW ISSUE: 3989 [Guidelines] Suggested Format
> 
> 
> Asir, 
> I'm assuming this recommendation should also be applied to the primer 
> since it also contains things that could be encapsulated in the 
> "principles, constraints and good practice" categories. 
> 
> But, I'm also a little curious about what constitutes 
> "architecture" in
> your mind and within the W3C. 
> Are you suggesting that the "guidelines" document be renamed to be the
> "architecture of policy assertions"? 
> 
> Maryann 
> 
> Asir Vedamuthu <asirveda@microsoft.com> 
> Sent by: public-ws-policy-request@w3.org 
> 11/17/2006 08:56 PM 
> To
> <public-ws-policy@w3.org> 
> cc
> 
> Subject
> NEW ISSUE: 3989 [Guidelines] Suggested Format
> 
> 
> 
> 
> 
> 
> 
> 
> Title: Suggested format for the Guidelines document.
> 
> Description:
> 
> Guidelines and best practices in the Guidelines document [1] 
> are hidden
> in the prose. They are not easy to pull out.
> 
> Assertion authors would find it very useful if the Guidelines document
> identifies a scenario, articulates the problem statement at the
> assertion design level, enumerates the factors to be considered and
> highlights good practices.
> 
> The Architecture of the WWW document [2] is a good model to follow.
> Furthermore, providing the assertion authors with a list of good
> practice statements upfront (for instance [3]) would be very useful.
> 
> Justification: 
> 
> Guidelines and best practices are hidden in the prose. 
> Assertion authors
> need to read this document multiple times and dig for guidelines and
> best practices. If the guidelines are clear and easy to find, the WG
> (and other WGs such as I18N WG) will find it easy to review the
> document, build consensus and adopt them.
> 
> Target: Guidelines for Assertion Authors.
> 
> Proposal:
> 
> We suggest using good practice statements as the center stage to
> describe the guidelines for assertion authors. We request the WG to
> consider the following possibilities:
> 
> a) Use a format similar to the Architecture of the WWW document
> b) Provide a list of good practice statements upfront (after the Table
> of Contents or in the Introduction).
> c) Both a and b.
> 
> [1]
> http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy-g
> uidelines.
> html?rev=1.8&content-type=text/html;%20charset=utf-8 
> [2] http://www.w3.org/TR/webarch/ 
> [3] http://www.w3.org/TR/webarch/#p10 
> 
> Regards,
> 
> Asir S Vedamuthu
> Microsoft Corporation
> 
> 
> 
>

Received on Thursday, 30 November 2006 23:39:59 UTC