Re: (Editorial): What shall we do with the Reference Guide?

On 7/7/15 4:16 PM, Holger Knublauch wrote:
> A few weeks ago we had inconclusive discussions about a vocabulary
> reference document, which would be auto-generated from the Turtle file
> to show all kinds of geeky details in human-readable form.
>
> A current version of this document is at
>
>      http://w3c.github.io/data-shapes/shacl-ref/
>
> (I have recently added some auto-generated, clickable class diagrams
> that are hopefully useful).
>
> The question is what to do with this document. I can see four ways forward:
>
> 1) Drop this idea and continue with the hand-crafted main document only.
-1
>
> 2) Merge its content as a (long) Appendix into the main document.
-1 (too long, and has value as a separate reference)
>
> 3) Publish it as a stand-alone document, e.g. "SHACL Vocabulary Reference".
+1
>
> 4) Publish it as part of a stand-alone document that focuses on the
> SPARQL aspects, e.g. as "SHACL SPARQL Execution".
-1 If this has SPARQL aspects then all of SHACL has them and we have a 
huge problem. I would suggest that:
1.3.6 sh:SPARQLExecutable
be explained as the model property for other executables.

kc

>
> I believe Option 2) will be most consistent if we plan to keep
> everything in a single place. Option 3) may make updating a bit easier
> and the main document shorter. Option 4 may have the advantage that we
> could take some SPARQL-based details out of the main document and move
> them into a stand-alone document. This could include sections on support
> for SPARQL endpoints or similar SPARQL-only implementation details.
>
> I have no strong opinion either way, but I'd appreciate some guidance
> from the group as this document is currently unlinked.
>
> Thanks,
> Holger
>
> PS: Before people jump on this, let me clarify that the current snapshot
> includes some not-yet-approved features such as the cleaned up scoping
> mechanism. I will of course synchronize this whatever we intend to
> publish as FPWD.
>
>
>

-- 
Karen Coyle
kcoyle@kcoyle.net http://kcoyle.net
m: 1-510-435-8234
skype: kcoylenet/+1-510-984-3600

Received on Wednesday, 8 July 2015 17:46:42 UTC