[Bug 4253] Basic Concepts section on Policy does not explain usage reasonably

http://www.w3.org/Bugs/Public/show_bug.cgi?id=4253

           Summary: Basic Concepts section on Policy does not explain usage
                    reasonably
           Product: WS-Policy
           Version: FPWD
          Platform: Macintosh
               URL: http://dev.w3.org/cvsweb/~checkout~/2006/ws/policy/ws-
                    policy-primer.html?content-
                    type=text/html;%20charset=utf-8#simple-message
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Primer
        AssignedTo: fsasaki@w3.org
        ReportedBy: william.henry@iona.com
         QAContact: public-ws-policy-qa@w3.org


Title: Basic Concepts section to Policy in primer does not explain attachment

Description: Section 2.2. is basically an introduction to to why someone might
use policy and explains this from the point of view of a simple SOAP message
that wants to use WS-Addressing.  The section then shows a simple policy to
cover this case. However the example just mentions that the policy can be
attached to the WSDL binding. It doesn't show how this is done. Surely this is
fundamental for a new user of Policy. I think that this first example should
demonstrate how the policy might be simply attached to a binding in a WSDL. 

Justification: For a new user of WS-Policy thePrimer should be explaining why
you might use policy (this section does that), and how you would use a policy -
two parts a) how to express it (section does that) and b) how to use the
expression (section just mentions this but does not show an example - a simple
one would suffice).

Proposal: Change this section to add an example that shows the policy defined
in the example attached to a binding in the WSDL. 

<wsdl:binding name="AddressingBinding" type="tns:RealTimeDataInterface" >
  <Policy>
        <wsap:UsingAddressing />
  </Policy>
  <wsdl:operation name="GetRealQuote">…</wsdl:operation>
  …
</wsdl:binding>

Notice that this example does not use any references but shows the most basic
way of attaching to a binding.

The section can then point to the section on How to attach Policy to WSDL.

Note: Referencing the attachment section will not suffice as the attachment
section only shows how to attach using a reference. (separate issue to be
raised)

Received on Wednesday, 17 January 2007 23:20:29 UTC