[Bug 4660] [Guidelines] Best Practice Statments should be statements

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

           Summary: [Guidelines] Best Practice Statments should be
                    statements
           Product: WS-Policy
           Version: FPWD
          Platform: All
        OS/Version: All
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Guidelines
        AssignedTo: mhondo@us.ibm.com
        ReportedBy: chrisfer@us.ibm.com
         QAContact: public-ws-policy-qa@w3.org


Title: Best Practice Statments should be statements
Target: Guidelines
Description: The current section on Best Practices has incomplete "phrases"
instead of statements.  The proposal has 2 parts and an option on the second
part:

Part 1 is to change these phrases to be statements

Part 2 is to reorganize them (and possibly renumber them).
Option A-- 
   reorganize within current table which is right now just a generated list of
BP's as they occur within the document.....so its not known how much work is
needed to do a "reorg" and whether it would be acceptable to move sections
around so that the "auto generation" happens in the correct order.

Option B-- is to put an additional table in the document which groups the Best
Practices logically ( an example of this is that the first best practice
included bullets which are really best practices later in the document).
-------------------------------------------------------------------------------
<current text for Best practice 1: Parts of an Assertion Specification>

Assertion Authors should include the following items in an assertion
specification: 
•       The definition of the assertion's semantic. 
•       The specification of the set of valid policy subjects to which an
assertion may be attached.
•       The scope of the assertion in the context of a particular policy
subject.
•       Any composition considerations if the assertion is used with other
assertions in a context.
-------------------------------------------------------------------------------



Part 1: 

<change from>
1. Parts of an Assertion Specification

2. Semantics Independent of Attachment Mechanisms

3. Semantics Independent of the Form

4. Start with Simple Assertion

5. Use Unique QNames

6. Provide an XML Outline

7. Specify Semantics Clearly

8. Not Necessary to Understand a Message

9. Avoid Duplication of Assertions

10. Use Parameters for Useful Information

11. Use Nested Assertions for Dependent Behaviors

12. Enumerate Nested Assertions

13. Discourage Domain Specific Intersection

14. Assertions Document Ignorable Behavior

15. Ignorable Attribute in XML

16. Assertion XML should allow use of wsp:Optional attribute

17. Assertion description should explicitly indicate that wsp:Optional is
allowed.

18. Limit use of Optional Assertions

19. Consider entire message exchange pattern when specifying Assertions that
may be optional

20. Indicate use of an Optional Assertion

21. Assertion Authors Should Specify Policy Subject(s)

22. Choose the Most Granular Policy Subject

23. Define Semantics of Attachment to Multiple Policy Subjects

24. Specify Preferred Attachment Point for an Assertion

25. Describe Semantics of Multiple Assertions of Same Type

26. Specify Composition with Related Assertions

27. Use Independent Assertions for Different Versions of a Behavior

28. Change of the Policy Subject Over Time


----------
<change to> 
----------



Best Practice 1. What to include in an Assertion Specification
     Best Practice 6. Specify Assertion Semantics Clearly
     Best Practice 2. The semantics of an Assertion should be Independent of   
          Attachment Mechanisms
     Best Practice 3. The Semantics of an Assertion should be Independent of
          the Form
     Best Practice 8. The Assertion Semantic should not depend on the
          semantics of the Message
     Best Practice 21. Assertion Description Should Specify a Policy Subject
     Best Practice 22. Choose a Granular Policy Subject
     Best Practice 26. Specify Composition with Related Assertions
Best Practice 4. Start with Simple Assertion
Best Practice 5. Use Unique QNames
Best Practice 7. Provide an XML Outline for an Assertion 

<consider renumbering to 7a, 7b> 
     Best Practice 16. Indicating Optional Behavior in XML Outline
     Best Practice 15. Indicating Ignorable Behavior in XML Outline

Best Practice 9. Avoid Duplication of Assertions
Best Practice 10. Use Parameters for Additional Assertion Information
Best Practice 11. Use Nested Assertions for Dependent Behaviors
Best Practice 12. Declare Nested Assertions
Best Practice 13. Discourage Domain Specific Intersection
Best Practice 14. Declare Ignorable Behavior 
Best Practice 17. Declare Optional Behavior.
Best Practice 18. Limit use of Optional Assertions
Best Practice 19. Consider entire message exchange pattern when specifying
     Assertions that may be optional
Best Practice 23. Define Semantics of Attachment to Multiple Policy Subjects
Best Practice 24. Specify Preferred Attachment Point for an Assertion
Best Practice 25. Describe Semantics of Multiple Assertions
Best Practice 27. Use Independent Assertions for Multiple Versions of a 
     Behavior
Best Practice 28. How to change the Policy Subject Over Time

Received on Monday, 18 June 2007 12:20:53 UTC