Re: NEW DRAFT: Documentation and OA/OAX

Hi all, (and Happy New Year!)

Sorry, I'm reacting very late but I was truly interested in these issues and did not have any time... If it still can help, here are my two cents.

I like the idea of the 'chapters' as suggested by Stian, which could indeed concur with Jacco's suggestion of "core" and "extensions" while keeping one same document. It becomes easier to read and we can still split it easily in several documents, if we decide to publish several namespaces.

And I like the ideas of 'thematic' modules (focused on certain requirements) for these chapters. The CSS2 example is indeed frightening, but I believe that OA would not end up with that many modules.

But I don't support moving everything in one same namespace. I like another part of Jacco's suggestion, with one core and one *or several* extensions. One shouldn't shy away to put in an extension what is less stable and less needed.
And if you don't like the idea of having one catch-all extension then we can create several extensions: for example oa-selectors, oa-styles, or a oa-specificresources encompassing the two previous ones.
  
By the way the split should rather be between what is necessary to many (even if it's quite complex) and what is only needed by a few, than between what is simple and what is complex.
It turns out that what is widely needed is often what is simple, but sometimes it's impossible to avoid an odd pattern. And in such case, it's much easier for technology users to have this more complex but important part *not* presented at the same time as elements that may be simple but are of anecdotal use for them.

Anyway, the baseline is that we should aim at an organization (both for doc(s) and for ontology(ies)) which makes it very easy to switch from a split solution to a unified one, just based on what the size of the parts to read (and use) is, and on how stable and interdependent these parts are.

Some reaction on individual items (some of them motivating my position above):


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


A general feeling an always be revisited :-)
If Choice/Set/List fulfils a requirement for core OA, I don't see why it would be in an extension.


> * The OAX ontology tends to be seen as a dumping ground or staging area, which undermines the approach


I quite agree!


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


I believe that there will be ways to untangle the structure. Not every element in styles is dependent on elements on selectors, no?
If we end up with one big bag


> * A single ontology would make the modelVersion issue much easier to deal with


I quite strongly disagree.
In fact keeping the modelVersion feature (I may come back to this in another mail) would make the problem very painful if one keeps forcing an annotation to be associated with one modelVersion. Having one single ontology updated often because of changes in the "optional/less stable" parts will force adopters of the core technology to suffer unnecessary pains, wondering whether and how they must update the data they have to tell it's compatible with newer model versions, even if the parts they use has not changed.
It would be less dangerous, more flexible to have e.g. one modelVersion statement refering to oa-core-v1.1, one modelVersion statement refering to oa-styles-1.6, etc. This puts the burden of creating more complex data (and updating data) to the ones who use a bigger part of the model, not to these using only the core.

I'm also wondering whether having one namespace also makes maintenance by spec publishers unnecessary more difficult.
Here as in many other cases, a divide-and-conquer is likely to pay of.


> * It’s confusing to have multiple, very similar namespaces and to remember which one is which.


Yes. But with "thematic" extensions this would be more intuitive.


> * It can always be re-introduced later


If you're thinking "later-but-before-the-next-official-publication", I agree. But if you publish one big namespace and then split it, it means that you will deprecate elements (the ones moved from the big namespace to the new smaller ones). Which is not good!




> This made me think that *at the moment* perhaps what we need aren't formal specifications, but instead tutorials and guiding documents should receive more attention?  This would mean that we weren't bounded by some of the formality and permanence restrictions required of W3C specifications. Once the model is better understood, especially regarding the choices that have been made over the process, it would be easier to have more detailed discussions about the most appropriate way to move forwards.
>


Some kind of Primer would be useful, yes, probably based on the examples in the cookbook.
But I am convinced it would already be hugely useful to make the examples of the Data Model  "more real". Resources like <body1>, T1#xywz don't help much. It would be harmless to pick identifiers and string that actually mean something to the reader, even if you keep the examples super-simple.

Cheers,

Antoine



On 11/20/12 3:59 PM, Stian Soiland-Reyes wrote:
> It is not a asbsolute requirement in W3C that a single namespace corresponds to a single document. For instance, in PROV, we moved from having separate namespaces to using http://www.w3.org/ns/prov# across the different documents PROV-O and PROV-DM.
>
> It does bring it's own set of worries, such as if you resolve http://www.w3.org/ns/prov# for RDF/XML, you only get the PROV-O terms, and not PROV-AQ terms like prov:hasProvenance. In PROV, we intend to present a 'merged' ontology when you resolve the namespace, with the standalone ontologies reachable from the different documents. The HTML browser gets a landing page pointing to the different documents; this landing page and owl can be updated independently of recommendation track (for instance to fix syntactic errors or keep up with technical OWL spec changes).
>
> Some of these challenges disappear if you end namespace with a / rather than #, so individual terms can redirect to correct spec/owl.
>
> That said, I agree that the current split is not very ideal ; but I am not sure about going for a single document. I agree with Jacco in that a simple and straight forward 'core' specification makes it much more likely for the standard to be picked up, understood and used. It is a bit of the beauty of the current OA spec, in my view, and I think several things could be moved out of the current "core".
>
> So I would generally not prefer a big, merged document. Is that what you are proposing? I would not mind a single namespace though.
>
> The OAX could be made more of an "OA Expanded" rather than "OA Extended"; showing the preferred way to do common scenarios such as CSS styling, sets, HTTP headers and other more "complex" structures that perhaps do not need to be in the core. With this I would downgrade the OAX role as a sandbox. Such new features should be in additional mini specs before being formally added to OAX.
>
> I would not argue for a CSS2 kind of modular splitting.
>
> Another alternative is however to do a multipage split, so you get "chapters" that are not as independent as separate specs, but more modular than the single HTML. Many do however like to download and print, and this could be tricky unless a "all in one" alternative version is made available.
>
> On Thu, Nov 8, 2012 at 9:11 PM, Robert Sanderson <azaroth42@gmail.com <mailto:azaroth42@gmail.com>> 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
>
> --
> Stian Soiland-Reyes, myGrid team
> School of Computer Science
> The University of Manchester
>

Received on Friday, 4 January 2013 14:33:09 UTC