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

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.

2) Merge its content as a (long) Appendix into the main document.

3) Publish it as a stand-alone document, e.g. "SHACL Vocabulary Reference".

4) Publish it as part of a stand-alone document that focuses on the 
SPARQL aspects, e.g. as "SHACL SPARQL Execution".

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.

Received on Tuesday, 7 July 2015 23:17:11 UTC