Skip to content
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

Open
juusoautiosalo opened this issue Aug 17, 2022 · 6 comments
Open

Add section: How to read this document #73

juusoautiosalo opened this issue Aug 17, 2022 · 6 comments
Assignees
Labels
Editorial Non-normative change spec Issue on specification

Comments

@juusoautiosalo
Copy link

juusoautiosalo commented Aug 17, 2022

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:

  • The audience of the document.
  • Prerequisites to understand the specification.

I think especially the prerequisites are important. JSON-LD requires familiarity with JSON.

Do we require familiarity e.g. with

  1. YAML
  2. JSON-LD

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?

@gkellogg gkellogg added Editorial Non-normative change spec Issue on specification labels Aug 17, 2022
@gkellogg
Copy link
Member

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.

@juusoautiosalo
Copy link
Author

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:

  1. Keeping the nature of the YAML-LD spec as tech-first, and directing newcomers to the primer. This would mean removing the IT/non-IT professionals from the audience of the spec, leaving only software developers.
  2. Concentrate newcomer readability efforts on the primer.

@anatoly-scherbakov and @gkellogg what do you think?

@gkellogg
Copy link
Member

gkellogg commented Sep 1, 2022

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.

@anatoly-scherbakov
Copy link
Contributor

Agreed about having Best Practices & Primer as separate repositories.

Can those repositories be created?

@gkellogg
Copy link
Member

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.

@anatoly-scherbakov
Copy link
Contributor

@gkellogg thank you. I will look into filling them in when they're created.

gkellogg pushed a commit that referenced this issue Sep 13, 2022
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Editorial Non-normative change spec Issue on specification
Projects
None yet
Development

No branches or pull requests

3 participants