-
Notifications
You must be signed in to change notification settings - Fork 8
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add section: How to read this document #73
Comments
This issue was discussed in the August 17th meeting. Spec serves multiple audiences, and some need only understand YAML plus basic -LD concepts. Others will need to understand more about JSON-LD Syntax and still others the API. A future separate Primer might be included in this document, for now. |
I meant to bring up the following in the call, but as we didn't have time, here it is: I wasn't able to comment the pull request #80 before it was accepted, but after looking into it and browsing the current specification, I am starting to lean towards having the specification as a very technical document, and not focusing too much on making it reader-friendly. Instead, use the primer as a beginner-friendly introduction. The main motivation for this division: The main purpose (and most content) of the YAML-LD spec seems to be to specify the mapping between YAML-LD and JSON-LD, which is not very interesting content for Linked Data newcomers. Hence, we cannot achieve a very newcomer-friendly result anyway. (In contrast, the JSON-LD spec was defined more from scratch and is therefore more newcomer-friendly by nature. Earlier I thought that the YAML-LD spec could be of similar nature, but it is clearly not sensible.) Also, trying to make the spec newcomer-friendly would slow down the actual spec progress, which is of course not desired. So I would propose:
@anatoly-scherbakov and @gkellogg what do you think? |
While I think that the spec should have more introductory information (similar to JSON-LD 1.1, I generally agree that we should create a primer and direct people there for the easiest way to get on board with YAML-LD, similar to the JSON-LD Primer. IMHO, the primary concern of the spec should be to describe normative behavior that implementors can use to create implementations, along with a test suite and implementation report. Primers often come later in the development process, but I think now would be a good time to get started, as the needs of the primer can also drive the technical direction. I'd suggest we create a new repo (yaml-ld-primer), similar to that I suggested for yaml-ld-bp): #72 (comment). This allows the use of PR Preview for visualizing changes from PRs and serves as a natural way to separate concerns. |
Agreed about having Best Practices & Primer as separate repositories. Can those repositories be created? |
Yes, may need @pchampin's help, but we should be able to set up empty repositories for them today. |
@gkellogg thank you. I will look into filling them in when they're created. |
The JSON-LD specification contains a section "How to Read this Document".
That section defines two matters that I think are relevant in this stage of specification development:
I think especially the prerequisites are important. JSON-LD requires familiarity with JSON.
Do we require familiarity e.g. with
At least the current draft of the YAML-LD specification seems to require familiarity with JSON-LD. I'm not sure if this has been discussed and if it is wise to require familiarity with JSON-LD to read the YAML-LD spec.
As reference, the JSON-LD does not require knowledge of RDF as explained in the introduction: "JSON-LD is designed to be usable directly as JSON, with no knowledge of RDF [RDF11-CONCEPTS]."
Any opinions? Perhaps discuss this in the call?
The text was updated successfully, but these errors were encountered: