Re: PROV-ISSUE-331 (review-dm-wd5): issue to collect feedback on prov-dm wd5 [prov-dm]

I foolishly read an old version so I may be missing something, and in particular some of my high-level comments may already have been addressed.  In particular there is a lot of new material on collections that I haven't reviewed yet (will try after writing up comments on the constraints).  I've tried to check that the detailed comments I made haven't already been fixed.


> Can the document be released as a next public working draft? If no, what are 
> the blocking issues?

I don't have blocking issues.

> * Is the structure of the document approved?

No comment, since I read an out of date version.

> * Can the short name of the document be confirmed (in particular, for prov-n, 
> prov-dm-constraints, since request needs to be sent for publication)? 

I think the name PROV-DM is OK.  I'm not as certain that the way of splitting the content up makes sense, for example PROV-DM and PROV-N don't seem separable to me.  


High-level comments:

* I feel that the PROV-DM document takes a long time to get to the point.  We do not see any concrete examples of PROV notation (in PROV-N or PROV-O) until the end of section 2.  Moreover, the discussionfocuses on explaining the concepts in isolation rather than describing the high-level modeling problems they work together to solve.

Suggestion:  Move the PROV-N section to the beginning of sec. 2 and illustrate the concepts through examples.  Or, arguably this is redundant given that the primer does more or less the same thing: perhaps, simply drop section 2 and proceed to the specification.

* The main examples (sec 3.1, 3.2, 4.6) are too "meta" - why not restate them in more generic terms.  These examples about describing the WG's own activities sound a little self-centered.

Given that both the primer and ontology use extended examples, why not align with one or both of them?  

* I feel that the document doesn't lay things out in a logical order.  I think it would be helpful to list the basic or standard constituents first: they are currently in sections 4.3 and higher.  In particular, the fact that some attribute names are reserved is left implicit in several descriptions of examples, and not explicitly discussed in the corresponding section.  

* PLEASE say somewhere prominently what the convention(s) are for optional arguments.  Some are simply omitted (e.g. initial identifiers, attribute lists) while others are replaced by "-".  Please make sure that all of the examples make sense with respect to whichever convention is in use.

* Reading the document, I wondered why generation and use have time instants rather than intervals.  Why couldn't an activity use something over an interval, or generate something during an interval?  We should say why we only care about the end of generation and beginning of use.

* There are a LOT of parenthetical examples, which I think stand little chance of making sense to a reader who hasn't been following the mailing list.


Detailed comments:  (Quotes with starred substrings represent suggested edits.)

Why "people" and not "agents"?

Why do we say that the various aspects of the standards are necessary, rather than just appropriate?  There may be other ways of dong this.

Sec 1.  "very quickly" -> "quickly"
"extra-descriptions" -> "extra descriptions"
"interval " -> "intervals"

Section 4 provides the *definitions* of PROV-DM concepts, structured according to six components.


2.2: "A same entity" -> "The same entity" - this happens many times

2.6.  The activity in the example has the wrong number of arguments (the times are omitted, but I believe should be replaced with "-").  Also, the convention about missing arguments being written "-" is very important and should be explained somewhere prominently, with examples.  This happens many more times.

3.1.  "(some of which *locate* archived email messages, available to W3C Members)."

4.1.2.  The reserved attribute "type" is mentioned here.  Where is hte list of all reserved attributes?  Why not list them up front as part of the preliminaries?

4.1.3.  The first example in Generation: p1 and p2 should be in code font.

4.2.3.  The missing id arguments to wasAssociatedWith in the examples are not marked as "-".  Happens again in 4.2.4, 4.1.5, 4.1.6, etc.  Also, many missing attribute lists are omitted without being replaced by "-".  This is a sensible convention but is not stated anywhere.

4.2.4.  The examples discussed in the second paragraph are not mentioned anywhere else.  So say "For example" instead of "In the example".

4.2.4.  Here and elsewhere, the term "modalities of ..." is used to describe what the attributes are for.

4.2.4. "a funder agents" - case mismatch

4.3.1 " And to provide a completely accurate description of the derivation" -> "To provide a more accurate ..."

4.6. "extra-information" -> "extra information"

4.6.  Concerning annotations, why would I want to do this instead of directly putting the x and y positions on the entity?


4.7.4.[3,4]: Why are role and type attributes allowd to occur multiple times?  Ordinary attributes aren't (I thought).  If we want to allow multiple occurrences of attribute names, why stop with these two?


4.7.5 "the string "abc", the string "abc" " - repeated text



-- 
The University of Edinburgh is a charitable body, registered in
Scotland, with registration number SC005336.

Received on Monday, 9 April 2012 22:51:48 UTC