Uploaded image for project: 'OASIS Open Data Protocol (OData) TC'
  1. OASIS Open Data Protocol (OData) TC
  2. ODATA-214

Find consensus on "Additional artifacts"-section of multi component Work Products (and implement accordingly)

    XMLWordPrintable

    Details

      Description

      Although some current revisions of components of a main work product still have not filled in the section "Additional artifacts" on the title page, others do have first fill-in proposals: "[OData Core Part 2: URL Conventions, Version 1.0](https://www.oasis-open.org/committees/download.php/47898/odata-core-v1.0-wd01-part2-url-conventions-2013-01-15.doc)" and "[OData Core Part 3: CSDL, Version 1.0](https://www.oasis-open.org/committees/download.php/47899/odata-core-v1.0-wd01-part3-csdl-2013-01-15-RH.doc)".

      The proposed wording of the "templates" as provided by OASIS might irritate the reader, as it says:

      """
      Additional artifacts:

      This prose specification is one component of a Work Product which also includes:

      • list ...
        """"
        leading to an ever changing list, or a contradiction.

      Better seems to be inicating a list of *all* constituents, where the current component is ammended by the string "(this document)". Of course the introductory sentence SHOULD be adapted, to make it consistent.

      The text of the list items should match the title of the document where appilcable.

      So in the case of CSDL, on the one hand it is listed in "[OData Core Part 2: URL Conventions, Version 1.0](https://www.oasis-open.org/committees/download.php/47898/odata-core-v1.0-wd01-part2-url-conventions-2013-01-15.doc)" as:
      " * OData Common Schema Definition Language"
      whilst the document itself "[OData Core Part 3: CSDL, Version 1.0](https://www.oasis-open.org/committees/download.php/47899/odata-core-v1.0-wd01-part3-csdl-2013-01-15-RH.doc)"is titled (besides the prefix "OASIS OData Version 1.0 Part 3: "):
      "CSDL".

      I hereby suggest to not use our "invented" acronyms in top-level places of that kind (titles, other components listing etc.).
      Common acronyms/abbreviations like eg. ATOM, JSON or ABNF are of course ok, but things like CSDL might need explanation for a potential reader.

      Following this convention we then only have to ensure in later stages of standardization, that the linkage will remain consistent (w.r.t. formats), i.e. a link to eg. "csdl.xsd" MUST be independent from the format (Word, PDF, Html) of the referencing work product component, but eg. one link to the prose document "OData Common Schema Definition Language" should keep the navigating client within the format of the referrer.
      So as an example: Starting from an "OData Protocol" PDF document the link should go to the "OData Common Schema Definition Language" PDF-document, whilst the HTML version should point to HTML.

        Attachments

          Activity

            People

            • Assignee:
              handl Ralf Handl
              Reporter:
              sdrees Stefan Hagen
            • Watchers:
              0 Start watching this issue

              Dates

              • Created:
                Updated:
                Resolved: