Re: JSON-LD FPWD publication proposal

On 29 May 2012, at 19:09, Manu Sporny wrote:
> PROPOSAL: The RDF WG should publish the JSON-LD Syntax specification and
> a stripped down version of the JSON-LD API specification, with the
> framing algorithm removed, as FPWDs.

I'd add a couple of points:

1. The Introduction of the API spec is mostly a copy-paste from the syntax spec. Remove the duplication, and replace it with a link if appropriate. Don't force people to read the same thing twice just so that they are sure they're not missing something essential.

2. The API spec needs its own introduction that explains what's in the API spec. This needs at least one sentence for each of the algorithms and other major sections of the spec, explaining what that thing is and how it fits into the bigger picture of publishing, consuming and processing JSON-LD. A quick overview of the document's contents. The current lack of such a high-level overview in the API spec is a major flaw, and makes the document almost inaccessible to JSON-LD outsiders. I'd consider this a blocker for FPWD publication of the API spec.

3. The API spec should probably have one of those yellow Issue boxes near the beginning stating that the scope of the document, and what exactly is going to be included and excluded, is still somewhat unclear. (This is just to make clear that agreeing to FPWD publication does not necessary mean we agree to everything that's in there; RDF-WG members will need some time to review and understand the spec and how it all hangs together before being able to make informed commentary on what should and shouldn't be included.)

4. The API spec should have one of those yellow Issue boxes pointing out that the WebIDL's terminology needs better alignment with RDF Concepts.

5. My understanding is that the two “Contributing” sections in the two specs need to be changed to reflect the CG-to-WG transition of the documents.

If those changes can be made, I would +1 the proposal.

Best,
Richard

Received on Wednesday, 30 May 2012 07:44:52 UTC