Re: [odata] Organization of OData Documents

[Robin Cover <robin@oasis-open.org>]

OData team: it looks like excellent progress on design for the

discrete Work Products that will be used for development and

publication of the OData spec.  I think it's always a good practice

to use the term "Work Product" (rather than casual terms like

"specifications", "documents") since the latter are not defined

terms in TC Process, and TC Process presents the rules for

multi-part construction, balloting, approvals, etc ONLY in

terms of "Work Product."  Keeping that in mind will prevent a

lot of headaches.

You may want to delay the engraving of  "Part 0" in stone

for a moment (e.g., wait until Chet returns from vacation);

there's a draft formulation in process to recommend/require

that "Parts" in a Multi-Part Work Product begin enumeration

with natural counting viz., "1" not "0"...  

Cheers!

- Robin

-- 
Robin Cover
OASIS, Director of Information Services
Editor, Cover Pages and XML Daily Newslink
Email: robin@oasis-open.org
Staff bio: http://www.oasis-open.org/people/staff/robin-cover
Cover Pages: http://xml.coverpages.org/
Newsletter: http://xml.coverpages.org/newsletterArchive.html
Tel: +1 972-296-1783 

On Tue, Sep 18, 2012 at 7:08 PM, Michael Pizzo <mikep@microsoft.com> wrote:

I had agreed to take offline a discussion on how we would ideally organize the set of OData documents.

 

According to the OASIS categorization of documents, I believe we are best served by identifying three related Work Products as follows:

1.       Multi-part OData Core

a.       Part 0: Core protocol document (includes normative reference to ABNF text document)

b.      Part 1: URL conventions document

c.       Part 2: CSDL document (includes non-normative reference to textual XSD for CSDL)

2.       Standalone OData Atom format

3.       Standalone OData JSON format

 

Batch processing (which is small) should be incorporated into 1a).

This proposed organization seeks to:

1)      Clearly identify the core information that a reader needs to read to understand the specification (1a)

2)      Clearly identify the complete set of information that an implementer needs to implement the core specification (1)

3)      Identify multiple formats that may be used with (1)

4)      While minimizing the total number of documents

 

Thoughts?