[Bug 3720] Terms should be defined/targeted in the appropriate sections of the spec

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

           Summary: Terms should be defined/targeted in the appropriate
                    sections of the spec
           Product: WS-Policy
           Version: FPWD
          Platform: PC
               URL: http://www.w3.org/mid/80A43FC052CE3949A327527DCD5D6B2701
                    E6B3A2@MAIL01.bedford.progress.com
        OS/Version: Windows XP
            Status: NEW
          Severity: normal
          Priority: P2
         Component: Framework
        AssignedTo: fsasaki@w3.org
        ReportedBy: gdaniels@progress.com
         QAContact: public-ws-policy-qa@w3.org


(Mail thread for this issue begins at
http://www.w3.org/mid/80A43FC052CE3949A327527DCD5D6B2701E6B3A2@MAIL01.bedford.progress.com)

Title: Terms should be defined/targeted in the appropriate sections of the spec

Description:  The editors took an action at the last F2F to define terms such
as "policy", "policy alternative", etc, at the point which they are first
referenced in the Framework spec.  This has caused the introduction to become
very difficult to read, and links to be less than clear.  We should fix this.

Justification:  Although with best intentions, the change in the current drafts
really didn't work as hoped.  The introduction is cluttered and hard to read,
and the links to terms such as "policy" go back there instead of to the place
where they are truly specified (sec 3.3 for "policy").

Target: WS-Policy Framework

Proposal:  We should remove the definitions and brackets from the introduction,
and have all usages of the terms we define (even in the introduction) link to
the sections where those terms are normatively defined.  For "policy" this
would be section 3.3, for "policy assertion" section 3.1, etc.  This would
mirror usage seen in other specs, and make the document much cleaner.

Received on Wednesday, 13 September 2006 17:21:51 UTC