Re: Comments on ORG ED

Hi,
Thanks Richard for the very thorough review & comments.  On the telecon now & Dave has agreed to work through and update as appropriate within the next week or so.

Thanks again.

Cheers,
Bernadette
 
On Oct 1, 2012, at 10:32 AM, Richard Cyganiak wrote:

> I reviewed the ORG ED at [1]. See below for my comments. Note, I did not review the descriptions of individual classes and properties, but only the sections surrounding them, as well as the various interspersed bits of discussion.
> 
> I've marked some comments as "Important" to indicate that I personally think they would significantly improve the document.
> 
> Best,
> Richard
> 
> [1] http://dvcs.w3.org/hg/gld/raw-file/default/org/static.html
> 
> 
> 
> 1. Important: I'd prefer if the document was cleanly separated into two parts, where the second part is purely a reference of the classes and properties. Content like 7.1 or the intro to Section 10 should better be pulled up and presented before the class+property reference starts (before Section 6). Justification: I think very few people will read all the class+property reference front to back; but some may read all the early chapters front to back; so the bits of helpful discussion interspersed throughout the reference sections should be pulled out into the early chapters. Otherwise, they are too easy to miss.
> 
> 2. Important: I missed an alphabetic index of classes and properties. Maybe one could be added as an Appendix (that's where I'd look for it in the TOC), or in the “Overview of Ontology” section.
> 
> 3. Important: The document is very lax about the formal references (normative/informative), but just uses simple hyperlinks, or no form of hyperlinking at all. I'd expect to see documents such as the RDF, OWL(2), SKOS, SPARQL, and so on, formally referenced. As a guideline, if a normative section uses a word that isn't found in an average dictionary (or where the intended meaning differs from, or is more specific than, the dictionary meaning), then I'd expect this to be a pointer to the W3C spec or other document that defines the meaning. This starts with terms like Ontology, Class, Property, Concept Scheme, ...
> 
> 4. Abstract and Intro use the phrase "linked-data publishing". This use of "linked-data" as a hyphenated adverb (?) seems unusual.
> 
> 5. Important: "Overview of ontology" should come before Conformance and Namespaces. Giving overviews and examples very early in the document is good. The bullet-point outline at the beginning of the document should be hyperlinks into the document.
> 
> 6. Important: The section "Scope" seems unusual, as it's not in the TOC and occurs before the Intro. I can't remember seeing something like this before in W3C documents. Make this a sub-section of the Introduction?
> 
> 7. General remark: Conformance section: I like the approach of defining conformance in terms of "data interchange". Nice!
> 
> 8. Important: The point "it does *not* use terms from other vocabularies..." should make a bit clearer that it's okay to use other terms *in addition* to ORG terms. For example, it's okay to use both org:Organization and schema:Organization.
> 
> 9. Important: "Additional constraints in a profile MAY include:" This should make clearer that the following list is not exhaustive.
> 
> 10. Important: "URI sets" needs to be a reference/link
> 
> 11. I suggest adding an item to the list of possible profile constraints that refers to Section 7.1 (the fact that a profile may encourage the use of particular ways of modelling roles)
> 
> 12. owlTime prefix: I think using uppercase prefix letter is generally a bad idea, as it raises the possibility of having owltime and owlTime being different. On prefix.cc, this namespace is associated with the time: prefix.
> 
> 13. Overview of ontology: "This ontology was originally motivated by [data.gov.uk initiative]" -- IMO the historic genesis of the technology isn't very interesting here; the approach adopted in the ontology can be explained without mentioning that. The reference to data.gov.uk can be mentioned in the Acknowledgements
> 
> 14. Important: The overview diagram has a number of inconsistencies: foaf:Agent is shown with prefix, but VCard without. Some terms have, I think, their labels rather than the local name shown: "head of", "resulted from" (should be "headOf", "resultedFrom"?)
> 
> 15. Important: The reportsTo arrow near foaf:Agent is ambiguous, does it originate at Site or at foaf:Agent? Same for the postIn/hasPost arrow near Post.
> 
> 16. The Example subsection in Section 4 should be numbered and show up in the ToC, because readers might be looking for an example in the ToC.
> 
> 17. May I suggest that the Turtle examples would be improved by having no spaces before semicolons and periods? They are not necessary in modern Turtle and are sort of a "bad habit" from N3 days.
> 
> 18. "Note on style": Rename to something like "Note on modelling style"; the current title suggests it's about typographic conventions in the document
> 
> 19. Important: The document would be improved by hyperlinking all occurrences of org:XXX terms to their definitions in the document.
> 
> 20. In Section 6.6 when it talks about org:classification, SKOS should be mentioned.
> 
> 21. Section 7.1 should have a more descriptive title
> 
> 22. The set of CONSTRUCT queries in 7.1 should be broken up into individual CONSTRUCT queries; the legal syntactic construct here is the individual SPARQL query. It might also make sense to move the individual CONSTRUCT queries to the appropriate place in the discussion; for example, the last one should be further up where org:roleProperty is discussed.
> 
> 21. General remark: The discussions of modelling alternatives, and when each alternative is more appropriate, and the use of SPARQL Construct to document equivalences between alternatives, are *great*.
> 
> That's all!