tutorials

[lazlop]

https://diataxis.fr/tutorials-how-to/#understanding-the-distinction

A tutorial’s purpose is to help the pupil acquire basic competence.

---

@steveraysteveray @pdelgosha22 @gtfierro @MatthewSteen

What are your thoughts on a tutorial on some of the basic processes for using 223P accomplished using RDFLib? I outlined this in this file. I think it may be helpful to have a more "beginning to end" type of tutorial to show people how to interact with 223P models, but I'm not sure exactly what should be included in this. Please edit the file or let me know what you think in this issue!

[steveraysteveray]

I think it's a good idea, but the tutorial should not leave anything to chance. It should provide exact commands for the reader to execute, with existing models, etc.

[MatthewSteen]

As I mentioned in the meeting today, I think it's nice to keep Tutorials and Guides concise and focused so that they're not covering a lot of material. Here are some other ideas.

1. Since tutorials are learning-oriented, I think it's helpful to ask "what do we want the user to learn?" from each one. In BuildingMOTIF we even explicitly stated what the learning objective (purpose) was at the top of the tutorial.

2. I think it's nice to use the same simple model for these so there's a common foundation throughout. The 223p G36 VAVR would probably be a good choice for these.

3. I like the idea of an RDFLib focused tutorial and a separate PySHACL tutorial. However, I don't think we should try to teach users how to use these tools in much depth/detail, that's what the tool's respective documentation is for. For these, we could also sprinkle in a little semantic web tech content, which would eliminate/reduce the https://github.com/open223/docs.open223.info/blob/main/explanation/supporting-tech.md.

Tutorials

Model Loading

RDFLib focused tutorial that covers the following.

1. Parsing an existing model (fetch from a raw GitHub url in the models.open223.info?)
2. A couple/few basic operations on the model.
3. A nice idea here would be to edit the model with RDFLib to make an invalid G36 model that will fail in the next tutorial, which could be saved alongside the MD file when the code is executed.

Model Validation

PySHACL focused tutorial that covers the following.

1. Validating the G36 model (fail).
2. Fixing the model.
3. Validating again (pass).

Others

I think the (2) tutorials above are the basic foundation and the other existing files there could be (re)moved.

[MatthewSteen]

Here are the ones that were listed in the original intro.md (landing/root page) for discussion.

Tutorials

• Using 223 Explore
• Using Query 223
• Tutorials for Model Creation Tools
  • Link to BMotif
  • link to Bob
  • TopBraid Composer
• Using RDFLib and PySHACL (or topbraid) to Create, Query, and Validate

[gtfierro]

I agree with @MatthewSteen that these want to be separate tutorials: loading + manipulation + serializing, and validation+fixing+revalidation. The code should run as-is; ideally we get these to run as part of the build process using code-cells

The models.open223.info page is in-progress but I'm still working out some kinks. I like the idea of loading in the models from those permalinks

[MatthewSteen]

I suggest moving the following existing tutorials, which I think are a better fit for #13 (references).

Using 223 Explore
Using Query 223
Using Model Building Tools

[MatthewSteen]

With the suggestion above, I think we should try to include https://explore.open223.info/ and https://query.open223.info/ in the first tutorial with links to the to the Reference page for the tools. Something like...

Model Loading

1. Parsing an existing model (fetch from a raw GitHub url in the models.open223.info?)
   Describing the model and linking to relevant classes, e.g. https://explore.open223.info/brick/Variable_Air_Volume_Box_With_Reheat.html.
2. A couple/few basic operations on the model.
   For example, performing a query using RDFLib and https://query.open223.info/.

[lazlop]

For the model loading and validation tutorials, I agree with all the feedback. I was planning to use this model G36 VAV model when the link was live. Thank you Gabe!

I think moving the model building tools to reference makes sense (since we will just have descriptions in this repo). I'm not sure about the tutorials for using explore.223 and query.223 since there are no tutorials elsewhere, but moving that discussion to the other issue!

[MatthewSteen]

For the model loading and validation tutorials, I agree with all the feedback. I was planning to use this model G36 VAV model when the link was live. Thank you Gabe!

@lazlop great! I suggest using a G36 VAVR model if possible, which is a little more interesting and probably one of the most common pieces of equipment in commercial buildings.

[MatthewSteen]

We had a quick meeting today and decided to add another tutorial...

1. Model Loading
2. Model Inferencing
3. Model Validating

[lazlop]

We may not want to separate inference and validation into two tutorials, because they're done in the same process. In your conversation, was querying included in model loading?

[gtfierro]

They don't have to be part of the same process. Inference is just as important for querying

[lazlop]

So maybe the tutorials can be

1. model loading (including sparql select queries)
2. model Inference and Update (including inference and sparql update)
3. model validation

[MatthewSteen]

For querying in Tutorial 1, I was thinking we could just use RDFLib for a simple one as an example and have a link to query.open223.info for another example of how to query a model.