Uploaded image for project: 'Technical Advisory Board'
  1. Technical Advisory Board
  2. TAB-1381

Sect. 2 titled 'Conformance' causes confusion

    XMLWordPrintable

    Details

    • Type: Bug
    • Status: New
    • Priority: Major
    • Resolution: Unresolved
    • Affects Version/s: OSLC Core Specification v3.0 WD
    • Fix Version/s: None
    • Component/s: Pre-public reviews
    • Labels:
      None
    • Environment:

      Style

    • Proposal:
      Hide

      See OData Part 1 for a practical example: http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398196

      In place of the current organization of the first few sections, I strongly recommend going with an organization like:

      • 1 Introduction
        1.1 Terminology
        1.2 References
        1.3 Typographical Conventions

      Where the Normative and Non-Normative References would go (in place of the Appendix) and what is now under "Conformance" would go under Typographical Conventions.

      The labels are suggestions. This however would address several of the comments.

      Show
      See OData Part 1 for a practical example: http://docs.oasis-open.org/odata/odata/v4.0/errata02/os/complete/part1-protocol/odata-v4.0-errata02-os-part1-protocol-complete.html#_Toc406398196 In place of the current organization of the first few sections, I strongly recommend going with an organization like: 1 Introduction 1.1 Terminology 1.2 References 1.3 Typographical Conventions Where the Normative and Non-Normative References would go (in place of the Appendix) and what is now under "Conformance" would go under Typographical Conventions. The labels are suggestions. This however would address several of the comments.

      Description

      There is also a section 2 in the documents titled "Conformance." It includes a general statement about normative / non-normative sections and the statement about use of keywords. I found this confusing because I thought it was intended to be the Conformance Clauses section. It wasn't until I found section 7 "Implementation Conformance" that this was cleared up.

      To avoid this confusion and keep the organization of this spec in line with common practice in the published OASIS works, see the proposal below.

        Attachments

          Activity

            People

            • Assignee:
              Unassigned
              Reporter:
              chet-oasis Chet Ensign
            • Watchers:
              1 Start watching this issue

              Dates

              • Created:
                Updated: