[OASIS Issue Tracker] Created: (ODATA-214) Find consensus on "Additional artifacts"-section of multi component Work Products (and implement accordingly)

[OASIS Issues Tracker <workgroup_mailer@lists.oasis-open.org>]

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

                 Key: ODATA-214
                 URL: http://tools.oasis-open.org/issues/browse/ODATA-214
             Project: OASIS Open Data Protocol (OData) TC
          Issue Type: Improvement
          Components: OData ATOM Format v1.0, OData CSDL v1.0, OData JSON Format v1.0, OData Protocol v1.0, OData URL Conventions v1.0
    Affects Versions: WD01
            Reporter: Stefan Drees
            Priority: Minor
             Fix For: WD01


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 a 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)" has is titled "CSDL". 

I would suggest to not use the "invented" acronyms in top-level places of that kind. ATOM, JSON, ABNF etc. are all ok, but CSDL might need explanation to a potential reader.

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


-- 
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators: http://tools.oasis-open.org/issues/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira