Apply suggestions from code review

Co-authored-by: Eli Chadwick <[email protected]>

Author: a-mile

episodes/03-root.md

@@ -42,7 +42,7 @@ If the crate is being served from a Web service,
 such as a data repository or database where files are not organized in folders,
 then the `@id` might be an absolute URI instead of `./`
 -- this is one reason why we point to the root entity from the metadata descriptor,
-see section [Root Data Entity](https://www.researchobject.org/ro-crate/specification/1.2/root-data-entity.html) for details.
+as you will see in the next section.
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 :::::::::::::::::::::::::::::::::::::::: challenge
@@ -68,8 +68,7 @@ see section [Root Data Entity](https://www.researchobject.org/ro-crate/specifica
 
 The root has several metadata properties that describe the RO-Crate as a whole,
 considering it as a Research Object of collected resources.
-The section on [root data entity](https://www.researchobject.org/ro-crate/specification/1.2/root-data-entity.html)
-details further the required and recommended properties of the root `./`. 
+In the next section we will cover the required and recommended properties of the root `./`.
 
 :::::::::::::::::::::::::::::::::::::::: keypoints
 - The RO-Crate Root is the top-level object of the RO-Crate

episodes/06-cross-references.md

@@ -9,7 +9,7 @@ exercises: 4
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 
 :::::::::::::::::::::::::::::::::::::::: objectives
-- Understand cross-references in RO Crate
+- Understand cross-references in RO-Crate
 - Add a data entity reference from the root entity
 ::::::::::::::::::::::::::::::::::::::::::::::::::
 

episodes/08-contextual-entities.md

@@ -24,6 +24,7 @@ A contextual entity might describe:
 - The software that processed the data
 - The instrument that captured it
 - The project that funded it
+- The people that contributed to creating it
 
 These entities don’t contain data themselves but give semantic context to the data you’re describing.
 

episodes/14-common-pitfalls.md

@@ -46,14 +46,14 @@ Creating RO-Crate packages by hand is a great way to understand their structure,
 ### 3. Using nested JSON instead of flat structure
 
 - **Problem**: Embedding full descriptions of related entities instead of referencing them with `@id`.
-- **Fix**: Use cross-referencing. Define each entity once and refer to it using its `@id`.
+- **Fix**: Use cross-referencing. Define each entity once in the `@graph` array and refer to it using its `@id`.
 
 ### 4. Repeating or mismatched @id values
-- **Problem**: Accidentally defining two entities with the same @id, or referencing an entity with an @id that doesn’t exist.
-- **Fix**: Ensure every @id is unique and points to an entity defined in the metadata.
+- **Problem**: Accidentally defining two entities with the same @id, or referencing an entity with an @id that doesn’t exist in the `@graph`.
+- **Fix**: Ensure every @id is unique and cross-references point to an entity defined in the metadata.
 
 ### 5. Forgetting required metadata on key entities
-- **Problem**: The root dataset doesn’t have name or license, or files are missing type.
+- **Problem**: The root dataset doesn’t have `name` or `license`, or files are missing `@type`.
 - **Fix**: Always include the required fields for the root (./) and for files:
 ```json
 {
@@ -93,6 +93,28 @@ Here's an incorrect metadata example. Identify and fix the issues.
 5. Missing required properties (description, datePublished, license) on the root dataset.
 ::::::::::::::::::::::::::::::::::::::::
 
+## RO-Crate validation tools
+
+The [RO-Crate Playground](https://ro-crate.ldaca.edu.au) and the [rocrate-validator](https://rocrate-validator.readthedocs.io/en/latest/) Python package can both be used to check for errors in your RO-Crate metadata. Each of them performs a different set of checks.
+
+:::::::::::::::::::::::::::::::::::::::: challenge
+
+Copy and paste your completed JSON-LD into the [RO-Crate Playground](https://ro-crate.ldaca.edu.au), then click "Validate". Are there any issues?
+
+::::::::::::::::::::::::::::::::::::::::
+
+:::::::::::::::::::::::::::::::::::::::: challenge
+
+Install the [rocrate-validator](https://rocrate-validator.readthedocs.io/en/latest/) and run it on the command line against your completed RO-Crate:
+
+```
+rocrate-validator validate <path_to_rocrate>
+```
+
+Are there any issues? Are the results different to the RO-Crate Playground?
+
+::::::::::::::::::::::::::::::::::::::::
+
 :::::::::::::::::::::::::::::::::::::::: keypoints
 - Include a metadata descriptor with @id: "ro-crate-metadata.json" and @type: "CreativeWork"
 - Ensure each referenced @id is also defined as an entity in @graph