RE: Comments on Guidelines document

Hi Frederick, 

I have not gone through all your comments yet in detail, but let me thank you for making the pass and providing feedback/corrections. We will apply the comments that are editorial. If there is an issue/clarification needed,  we will bring as a separate issue. 

Thanks again, 

--umit

> -----Original Message-----
> From: public-ws-policy-request@w3.org 
> [mailto:public-ws-policy-request@w3.org] On Behalf Of Frederick Hirsch
> Sent: Thursday, Oct 05, 2006 7:40 AM
> To: public-ws-policy@w3.org
> Cc: Hirsch Frederick
> Subject: Comments on Guidelines document
> 
> 
> Comment on Guidelines Document
> Web Services Policy 1.5 - Assertion Authors Guideline for WS-Policy
> 
> Editors' copy $Date: 2006/10/05 06:27:08 $ @@ @@@@ @@@@
> 
> <http://tinyurl.com/gxrh3> or
> <http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy- 
> assertion-guidelines.html?content-type=text/html;charset=utf-8>
> 
> Comments on Content
> 
> 1) Add wsp:Policy elements to Example 8.4 CompanyAProfileB (fully  
> expanded), and also example 8.6
> - wsp:Policy element required as child of sp:TransportBinding and  
> parent of sp:TransportToken, since sp:TransportToken is an assertion.
> 
> 
> 2) Is this statement at end of section 4 true?
> 
> "For example, when multiple alternatives are present in a policy  
> (designated by multiple wsp:exactlyOne, the compact form can not be  
> used."
> 
> A compact form policy can imply multiple alternatives through 
> the use  
> of wsp:Optional.  ExactlyOne can also be used in compact form, as  
> noted in 4.3 of Framework.
> 
> 3) Section 5 states "The model is an opt-in model".
> 
> Not sure this really makes sense or should be stated here. Isn't opt- 
> in generally used with regards to privacy? Is there such a thing as  
> an opt-out policy description? Suggest removing this sentence.
> 
> 4) Add guidance as to when and why to use parameters versus nested  
> assertions. I think it would make the document flow better and be  
> clearer if section 5.4 "Assertions with Parameters" were to be  
> combined with 5.5 "Comparison of Nested and Parametrized Assertions"  
> and placed before 5.3 "Nested Assertions". This could answer the  
> question of when to use parameters versus  nested assertions before  
> getting into the details of nested assertions.
> 
> 5) Add description and guidance related to policy and SOAP  
> intermediary processing, before section 5.6 Self Describing Messages
> 
> 
> Editorial comments
> 
> 1) There still seem to be a spurious characters in document, perhaps  
> formatting statements that were not processed. For example in last  
> sentence of section 2 "�cookbook� ", and "don�t" (2 
> times), and  
> in examples 8.2 ("<sp:TransportBinding>�</spTransportBinding>"),  
> 8.3 ("�"), 8.5 (" �`") and 8.6 (" �" and "��.."�").
> 
> 2) Pretty-print (indent) all xml for readability
> 
> 3) section 1
> 
> replace
> "
> The focus of this document is to capture best practices and usage  
> patterns for practitioners to follow as well as provide guidance to  
> achieve the best possible result. It is a complementary guide to  
> using the specifications and is intended to provide non-normative  
> descriptions to supplement the specification text.
> 
> This document is intended for use by:
> "
> 
> with
> "The focus of these guidelines is to capture best practices 
> and usage  
> patterns for practitioners to follow. It is a complementary guide to  
> the Framework and Attachments specifications and primer. It is  
> intended to provide non-normative guidelines for:"
> 
> 4) End of section 2
> 
> remove:
> "This document, then can also be considered a �cookbook� of  
> techniques and guidelines for the use of the framework. You don�t  
> have to follow the recipe, but you may not end up with the same  
> result if you don�t."
> 
> 5) Section 2.1, not past tense:
> 
> s/knowledge, it needed to/knowledge, it is necessary to/
> s/could/can/
> 
> 6) 2.1.1
> s/consistenly/consistently/
> 
> 7) in 2.1.2 replace
> 
> "In the degenerative case, a human could be capable of reading the  
> xml expression and could determine whether or not it was capable of  
> constructing a message that the service advertised."
> 
> with
> 
> "In the degenerate case, a human could read the xml and determine if  
> a message could be constructed conformant to the advertised policy."
> 
> 8) 2.1.3 s/can reflect its on the wire/can specify its on-the-wire/
> 
> 9) 3.1 5th paragraph
>   s/ (i.e.different alternatives)/(e.g. with different alternatives)/
> 
> 10) 3.1 first bullet
>   s/context or does the/context or is the/
> 
> 11) 3.1 second bullet
> s/Determination of the assertions subject is 
> helpful/Determination of  
> the subject  of an assertion is helpful/
> 
> 12) 3.1 third bullet
> s/how does//
> s/\?//
> 
> 13) in 5.2 last paragraph, start with simpler one, add "also",
> 
> replace
> 
> "Domain authors are encouraged to look at WS-SecurityPolicy [ADD  
> REFERENCE HERE doc references] to see an example of a complex domain  
> that has been decomposed into a set of policy expressions. New  
> aurthors are encouraged to look at WS-ReliableMessaging 
> Policy to see  
> an example of a simple domain that has only defined 2 assertions."
> 
> with
> 
> "New aurthors are encouraged to look at WS-ReliableMessaging Policy  
> to see an example of a simple domain that has only defined 2  
> assertions. Domain authors are also encouraged to look at WS- 
> SecurityPolicy [ADD REFERENCE HERE doc references] to see an example  
> of a complex domain that has been decomposed into a set of policy  
> expressions. "
> 
> 14) 5.3 3rd paragraph
> 
> s/what algorithm suite/the algorithm suite/
> 
> 15) 5.4 1st bullet
> 
> s/which can not/that cannot/
> 
> 16) 5.6
> put last paragraph first removing "REWRITEAs a result,". This last  
> paragraph is the main concept. Tighten earlier material.
> 
> regards, Frederick
> 
> Frederick Hirsch
> Nokia
> 
> 
> On Oct 5, 2006, at 2:30 AM, ext Felix Sasaki wrote:
> 
> >
> > Hi all,
> >
> > I did my action item 125 "Felix to Input Guidelines doc in CVS".
> >
> > Please have a look at http://tinyurl.com/gxrh3 or
> > http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-policy- 
> > assertion-guidelines.html?content-type=text/html;charset=utf-8
> > .
> >
> > For the editors: the build.xml is updated respectively.
> >
> > Felix
> >
> 
> 
>

Received on Friday, 6 October 2006 19:31:16 UTC