Re: JSON-LD FPWD publication proposal

On 05/30/2012 03:44 AM, Richard Cyganiak wrote:
> 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.

Ok, I'll remove the duplication and re-write the introduction to be more
specific to the JSON-LD API.

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

I'll add a high-level overview of why each method exists.

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

I will add that.

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

Yep, will do.

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

Yes, the assumption is that would have to change before the FPWD is made.

Tracking all of these comments in this issue:

https://github.com/json-ld/json-ld.org/issues/127

-- manu

-- 
Manu Sporny (skype: msporny, twitter: manusporny)
Founder/CEO - Digital Bazaar, Inc.
blog: PaySwarm Website for Developers Launched
http://digitalbazaar.com/2012/02/22/new-payswarm-alpha/

Received on Wednesday, 30 May 2012 14:58:30 UTC