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-primer.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-guidelines.
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:17:50 UTC