Add section: How to read this document

[juusoautiosalo]

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]

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]

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]

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): https://github.com/json-ld/yaml-ld/issues/72#issuecomment-1233397611. This allows the use of PR Preview for visualizing changes from PRs and serves as a natural way to separate concerns.

[anatoly-scherbakov]

Agreed about having Best Practices & Primer as separate repositories.

Can those repositories be created?

[gkellogg]

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]

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