Re: Comments on draft #3

Karen,

+1.

I also had stylistic comments but didn't want to detract from the
audience issue. I completely agree that examples should look
realistic. It makes them easier to understand and remember. Ideally, a
common theme for the examples should be used, perhaps elaborating some
document to illustrate each new feature.

I also agree with moving the Constraint Validation Vocabulary after
the Property Constraints. Readers want immediate gratification so they
should see a SHACL document as early as possible.

-- Arthur

On Thu, Mar 19, 2015 at 10:40 AM, Karen Coyle <kcoyle@kcoyle.net> wrote:
> These comments, IMO, would help bring the first portion of the draft closer
> to Arthur's #1 document:
>
> 1. Add an introductory section that defines the sections of the documents.
> Designate sections 2-4 as SHACL CORE.
>
> 2. Move the section on Constraint Validation Vocabulary after Property
> Constraints
>
> 3. For at least some examples, include:
>   - SHACL language
>   - Instance data
>   - Result
>
> 4. Where possible, make the examples look like "real data" - the examples in
> the SPARQL 1.1 Query Language[1] document could serve as an example of this.
> Also, using familiar vocabularies like FOAF or dcterms in the examples will
> make them easier to comprehend. (I am willing to mock up some simple
> examples if that helps.)
>
> kc
> [1] http://www.w3.org/TR/2013/REC-sparql11-query-20130321/
> --
> Karen Coyle
> kcoyle@kcoyle.net http://kcoyle.net
> m: 1-510-435-8234
> skype: kcoylenet/+1-510-984-3600
>

Received on Thursday, 19 March 2015 22:37:56 UTC