Re: NEW DRAFT: Documentation and OA/OAX

I think this is a wise decision and will make the spec more comprehensible and usable.

Tim Clark




On Nov 8, 2012, at 4:11 PM, Robert Sanderson wrote:

> 
> 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



The information in this e-mail is intended only for the person to whom it is
addressed. If you believe this e-mail was sent to you in error and the e-mail
contains patient information, please contact the Partners Compliance HelpLine at
http://www.partners.org/complianceline . If the e-mail was sent to you in error
but does not contain patient information, please contact the sender and properly
dispose of the e-mail.