Merge pull request #6 from ross-spencer/gh-pages

Clarify some parts of the tutorial

_episodes/03-metadata-descriptor.md

@@ -16,7 +16,7 @@ keypoints:
 
 ## RO-Crate Metadata descriptor 
 
-The first JSON-LD _entity_ to add has the `@id` value of `ro-crate-metadata.json` to describe the JSON file itself:
+The first JSON-LD _entity_ to add in the `@graph` array has the `@id` value of `ro-crate-metadata.json` to describe the JSON file itself:
 
 
 ```json

_episodes/04-root.md

@@ -26,6 +26,13 @@ Next we'll add another entity to the `@graph` array, to describe the [RO-Crate R
 }
 ```
 
+> ## Adding entities to the JSON array
+>
+> Because we're adding incrementally to the `@graph` array. It is important to remember the comma `,` between each entity, **except** for the final entity in the JSON array; and likewise for the properties within the JSON object for each entity. This is an artefact of the strict [JSON](https://www.json.org/) file format rules to simplify parsing. The order of the entities within the `@graph` JSON-LD array and the order of the keys within a JSON object is _not significant_. The _graph_ content is given by the `@id` cross-references.
+>
+> You will add a comma here between the `ro-crate-metadata.json` entity, and the root data entity.
+{: .callout}
+
 By convention, in RO-Crate the `@id` value of  `./` means that this entity describes the folder in which the RO-Crate metadata file is located. This reference from `ro-crate-metadata.json` is therefore semantically marking the `crate1` folder as being the RO-Crate Root.
 
 

_episodes/09-contextual-entities.md

@@ -19,11 +19,6 @@ keypoints:
 
 Entities that we have added under `hasPart` are considered _data entities_, while entities only referenced from those are considered _contextual entities_ -- they help explain the crate and its content.
 
-> ## Adding entities to the JSON array
->
-> You may have noticed we're adding incrementally to the `@graph` array. It is important to remember the `,` between each entity, **except** for the final entity in the JSON array; and likewise for the properties within the JSON object for each entity. This is an artefact of the strict [JSON](https://www.json.org/) file format rules to simplify parsing. The order of the entities within the `@graph` JSON-LD array and the order of the keys within a JSON object is _not significant_. The _graph_ content is given by the `@id` cross-references.
-{: .callout}
-
 You may notice the subtle difference between a _data entity_ that is conceptually part of the RO-Crate and is file-like (containing bytes), while a _contextual entity_ is a representation of a real-life organization that can't be downloaded: following the URL, we would only get its _description_. The section [contextual entities](https://www.researchobject.org/ro-crate/1.1/contextual-entities.html) explores several of the entities that can be added to the RO-Crate to provide it with a **context**, for instance how to link to authors and their affiliations.  Simplifying slightly, a data entity is referenced from `hasPart` in a `Dataset`, while a contextual entity is referenced using any other defined property.
 
 ## Detailing licenses

_episodes/10-authorship.md

@@ -32,7 +32,7 @@ Moving back to the RO-Crate root `./`, let's specify who are the authors of the
 > > ```json
 > > {
 > >   "@id": "./",
-> >   "@type": "Dataset",
+> >   "@type": ["Dataset", "LearningResource"],
 > >   "author": {"@id": "https://orcid.org/0000-0002-1825-0097"},
 > >   "…": "…"
 > > },
@@ -92,7 +92,7 @@ The reuse of existing identifiers is important for both persons and organization
 > > ```json
 > > {
 > >     "@id": "./",
-> >     "@type": "Dataset",
+> >     "@type": ["Dataset", "LearningResource"],
 > >     "publisher": {"@id": "https://ror.org/05gq02987"},
 > >     "…": "…"
 > > }

_episodes/11-validating.md

@@ -60,11 +60,15 @@ If the document passes without errors in the JSON-LD Playground, you should see
 
 This verbose listing of the JSON-LD shows how the `@context` has correctly expanded the keys, but is not particularly readable. Try the _Visualized_ tab to see an interactive rendering of the entities:
 
+> ## Expanding the visualization
+>
+> Click on the circles to expand or collapse the details of the graph's different nodes.
+{: .callout}
+
 ![Visualized in the JSON-LD Playground](../fig/jsonld-playground-visualized.png)
 
 As the RO-Crate Metadata Document is valid JSON-LD it is also possible to process it using Linked Data technologies such as triple stores and SPARQL queries. It is beyond the scope of this tutorial to explain this aspect fully, but interested readers should consider how to [handle relative URI references](https://www.researchobject.org/ro-crate/1.1/appendix/relative-uris.html).
 As an example, try the _Table_ button and notice that the entities with relative identifiers are not included. This is because when converting to RDF you need absolute URIs which do not readily exist when a crate is stored on disk, we've not decided where the crate is to be published yet.  
 
 
 {% include links.md %}
-

_episodes/12-triples.md

@@ -15,7 +15,9 @@ keypoints:
 
 ## Advanced: Converting JSON-LD to triples
 
-Try modify the graph's `@context` within the [JSON-LD Playground](https://json-ld.org/playground/) (don't modify the `ro-crate-metadata.json` on disk), and revisit the _Table_ rendering.
+To convert the RO-Crate JSON-LD to triples, e.g. to demonstrate how it might be described at a web resource, a 'base' URI is needed that will point to that resource, i.e. resolve as a page or file on the web.
+
+Try to specify a hypothetical base URI by modifing the graph's `@context` within the [JSON-LD Playground](https://json-ld.org/playground/) (do not modify the `ro-crate-metadata.json` on disk), and revisit the _Table_ rendering.
 
 ```json
 {