NEW DRAFT: Documentation and OA/OAX

Dear all,

With the recent additions and modifications to the data model, as editors
we feel that the current split of the specification using OA/OAX as a
dividing line is no longer sustainable or useful.  Although it is our
prerogative as editors to choose the means we feel most appropriate to
convey the consensus of the community group, we of course value all of your
feedback and hence would like to discuss the issue openly.

The proposed structure for the specification is to follow the approach of
many larger specifications and have a table of contents page, which links
to different chapters and appendices.

The Table of Contents would look something like:

1. Annotation Basics
 1.1 Body and Target
    1.1.1 Typing of Resources
 1.2 Provenance
    1.2.1 Agents
 1.3 Motivations
 1.4 Style

2. Specifiers
 2.1 Selectors
    2.1.1 Fragment Selector
    2.1.2 Text Selectors
    2.1.3 Image Selectors
 2.2 State
    2.2.1 TimeState
    2.2.2 RequestState
 2.3 Scope

3. Cardinality and Structure
 3.1 Annotations without a Body
 3.2 Multiple Bodies and Targets
 3.3 Semantic Structures
    3.3.1 Choice
    3.3.2 Set/Composite
    3.3.3 List
    3.3.4 Application to Body, Target and Specifiers

4. Publishing Model
 4.1 Serialization formats
    4.1.1 Named Graphs
 4.2 Inline Resources
 4.3 Equivalency of Resources

Appendix A: Provenance Ontology Mapping

This and previous discussion brings into question the utility of the OA/OAX
split, and we propose to collapse them to a single namespace for the
following reasons:

* The current reasoning behind the split is not well understood, or adhered
to in decisions. For example, Choice/Set/List fulfils the requirements for
OA, yet the general feeling is that it should be in OAX. The same arguably
applies to Style.
* The OAX ontology tends to be seen as a dumping ground or staging area,
which undermines the approach
* OAX was also intended to allow documentation for the extension to be
updated separately from the core, however this would be impossible with the
above layout.  Two separate specifications with independent evolutions, yet
inextricably linked, is not a common pattern for W3C documents and likely
would be difficult in a Working Group environment rather than Community
Group.  We feel that the documentation issue is better solved by a layout
like that described above
* A single ontology would make the modelVersion issue much easier to deal
with
* It’s confusing to have multiple, very similar namespaces and to remember
which one is which.
* It can always be re-introduced later

Thanks for your feedback on this!

Rob & Paolo