[Bug 3989] [Guidelines] Suggested Format

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

           Summary: [Guidelines] Suggested Format
           Product: WS-Policy
           Version: FPWD
          Platform: PC
        OS/Version: Windows XP
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Guidelines
        AssignedTo: fsasaki@w3.org
        ReportedBy: asirveda@microsoft.com
         QAContact: public-ws-policy-qa@w3.org


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

Received on Saturday, 18 November 2006 01:31:03 UTC