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 Thursday, 5 October 2006 14:39:50 UTC