JSON-LD API introduction with plenty of examples #127

Closed
msporny opened this Issue May 23, 2012 · 8 comments

Comments

Projects
None yet
2 participants
Owner

msporny commented May 23, 2012

@cygri has raised a number of concerns about the JSON-LD API spec that could be resolved by adding a good high-level introduction to the specification as well as plenty of examples showing how a developer could use the API to achieve certain tasks. Namely:

  1. Introduction to basic API functionality with simple code examples.
  2. Examples of converting to RDF from JSON-LD and to JSON-LD from RDF.
Owner

msporny commented May 30, 2012

More from @cygri:

  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.

In a prominent place in the FPWD, document the intention to align with the RDF model and terminology. This will calm the RDF community and reduce the comments requesting something you already plan to do.

Owner

msporny commented May 30, 2012

cygri: Guus, you said that you might want to be able to tell if it's gotten more public feedback?
cygri: Sandro already mentioned that it might go into the status of the document section - even though this is a FPWD, it already has an 18-month history elsewhere.
cygri: We should state this clearly in the status section.

Owner

msporny commented Jun 10, 2012

Addessed Guus and Sandro's concern in commits 2ddff70 and 056a046.

Owner

msporny commented Jun 10, 2012

Addressed @ericprud's issue in commit 056a046 and 944148f.

Owner

msporny commented Jun 11, 2012

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.

Re-wrote the entire introduction to be specific to the JSON-LD API spec. There is some duplication in terminology, but only because forcing the developer to jump between two documents is not an efficient way to read and implement a specification. ReSpec also doesn't allow one to easily cross-link terminology between documents.

The Introduction now contains a brief overview of the API calls in the specification with a number of API examples. These changes were made in commit 57d3fb7.

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.

Added a fairly in-depth introduction to the algorithms contained in the document in commit 57d3fb7.

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

This was added in commit 594e21f.

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

This was performed in commit 944148f.

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.

This has been done in commit 3728469.

Owner

msporny commented Jun 11, 2012

@cygri @ericprud - I believe that I have addressed all concerns raised in this particular issue. Please verify and let me know if you agree with the changes.

Owner

msporny commented Jun 23, 2012

Closing issue. No response from original commenters and all concerns have been discussed and addressed.

msporny closed this Jun 23, 2012

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment