[poe] Model editorial

riannella has just created a new issue for https://github.com/w3c/poe:

== Model editorial ==
@aisaac

4. Simple editorial suggestions:

- in 3.1 it would be good if the list of attributes could refer to the various sections that follow. And that these sections would be given in the order of the list! Otherwise the list’s explanations read quite rough.

- the order of subsections in 3(.1) seems quite unnatural. I don’t understand why I had to read about the intricacies of policy composition, conflict strategy or undefined actions before reading about the basics of rules and assets. This would for example caused me to ponder why ‘permission’ is used as a property in the JSON listings of example 1 and below, while it had been only refered to as a Class in the text so far.
Going through the model via a ‘depth-first’ approach for each class has some advantages, but it does really prevent a newcomer to get the basics right. Maybe a first section could explain the basic classes and relationships between them, and a second question would tackle the rest of complex issues, class by class. Such organization would also allow to put some debated constructs (Undefined Actions in 3.1.4) more towards at the end of the document.

- in 3.1.1 the sentence with ’irreducible’ could mention that the notion is exemplified afterwards. Since it’s in italics without explanation, it made me feel that I should understand it, while it had not been defined. And ‘unambiguous’ could be removed, as it’s not defined or exemplified anywhere, as far as I can tell.

- why is dct:isReplacedBy in bold in “If a Policy contains the dc:isReplacedBy property” in 3.1.2? It’s not in bold in the bullet list above.

- in 3.1.3 “the print Action is a subset of the use Action”. This is confusing when one thinks of RDF/OWL class/sub-class relationships with set semantics. print and use are not classes. It would be more exact to write “the print Action is a specialization of the use Action”

- identifiers of sections in the HTML document structure should be checked. E.g. 3.1.5 has ‘inhertiance’ as id.

- in 3.3.1 “additiion” -> “addition”

- in 3.4 “An ODRL policy expression MAY contain at least one Permission.” is not really informative from a semantic perspective. Except for correcting the wrong understanding that can be caused by the sentence just before it (see comment above). But if that sentence is fixed, then this one could be removed.

- in 3.6 “this is used to refer the same Duty to multiple Permission entities.” -> “this is used to refer from a Duty to multiple Permission entities.” ?

- in 3.8 “EU dollars”???

Please view or discuss this issue at https://github.com/w3c/poe/issues/163 using your GitHub account

Received on Tuesday, 2 May 2017 04:02:37 UTC