Re: Comments on ORG ED

[Sorry for possible double post, fat finger syndrome.]

On 01/10/12 15:32, 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.

Thanks for the detailed review Richard.

Given the extent of changes you suggest then other reviewers should hold 
off until these are addressed (one way or another). I can't guaranteed 
how quickly this will be possible, may not before the next Thursday call.

A couple of points to comment on.

When I get a chance to do more work on this I'll respond to the other 
points as I address them, many of them I agree with.

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

Slightly tricky.

Many of the current discussion sections do not have enough detail to 
easily stand alone, but are intended to just clarify usage of the 
classes and properties which are the heart of the specification. I'm not 
sure how interpretable they on their own. Furthermore the grouping of 
discussion/detail into sections is intended to make it easy to skip the 
sections irrelevant to your task.

However, maybe I'm guilty of providing the style of document I would 
prefer myself. If I can allocate more time to this then I'll try a 
version as you suggest and see how it turns out.

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

Agreed. This is not my section and seemed to have come from best 
practices. I deleted the most misleading parts of it but assumed it was 
some agreed working group boiler plate. I will just delete it.

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

:) Layout style for Turtle is even more a matter of taste than 
programming style but I'm OK with going along with this.

> 19. Important: The document would be improved by hyperlinking all occurrences of org:XXX terms to their definitions in the document.

Agreed.

I had considered this but ducked on the grounds that other GLD 
documents, include DCAT, use the external reference style.

Will reconsider that consideration :)

Dave

Received on Monday, 1 October 2012 15:18:46 UTC