reference

[MatthewSteen]

https://diataxis.fr/reference/

Reference guides are technical descriptions of the machinery and how to operate it. Reference material is information-oriented.

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

• Reference
  • Supporting Technologies References
    • Links documentation to SHACL, RDFS, RDF, SPARQL, etc.
  • Publication document?
  • Available Tools
  • Open 223
    • Explore 223
    • Query 223

[MatthewSteen]

@gtfierro what do you think about moving the descriptions of the sites listed at https://open223.info/ to the References section here? This would allow for expanding a bit and could potentially make the docs the entry point for users into the collection of supporting sites while removing some duplication.

[lazlop]

Yes! For the Open223 things I was just planning on descriptions and links.

I'm not sold on putting the tutorials for query223 and explore223 in the reference section for a few reasons. There are no other existing tutorials that exist for these resources anywhere else, so we are not just referencing another resources tutorial. Unless we release the publication document (which doesn't look likely) then these resources may be the main way people interact with the standard, so it would be good to have the tutorials more in a users path as they go through the documentation..

[gtfierro]

We can attach some documentation (tooltips, etc) to the tools themselves, but why not put full documentation for query/explore tools into the reference section? Where else would they go?

[MatthewSteen]

@lazlop see my #7 (comment) for how to include a bit of tool tutorial content into the first tutorial.

[lazlop]

@MatthewSteen I think referencing them in the tutorial on parsing and querying is a good idea.

Based on how I read the diataxis framework what I was imagining fit into the tutorial section not the reference section. I was thinking of doing a walkthrough of an example showing how to navigate each page (which would not be succinct, complete, or austere). @gtfierro If we are planning to fully document them in this repo then putting everything in the reference section seems fine!

[MatthewSteen]

@lazlop I think the Open223 tools are relatively self-explanatory and don't need a lot of documentation. Adding screenshots for navigating each page would require us to keep those up to date if the corresponding tool UI changes.

I think we could include concise descriptions of each page/tool (with link) and even combine the MD files into the following. What do you think?

• Reference
  • Open223 Models
    • 223-models.md
    • link to models.open223.info, which has more detailed documentation
  • Open223 Tools
    • 223-tools.md
    • Include links and concise descriptions of explore.open223.info, query.open223.info, and defs.open223.info.

[lazlop]

I'm ok with that, you can go ahead and make the change!
I was worried about people who have never used RDF not really understanding how the website was laid out or what UI elements mean, but that may have been too preemptive.

[MatthewSteen]

Great, thanks for the feedback! I'll put that in the PR above.

[MatthewSteen]

There was a open-223.md file with the following content that I removed in the PR above.

# Ontology

Ontology files available for download

Model

Vocab 

Inference 

Validation

[lazlop]

That is just a placeholder for us to link the actual ontology files (which we should make easily available for download). The ontology files are currently grouped into separate model, vocab, inference and validation files.

[gtfierro]

The files should be downloaded from data.ashrae.org, which is the host part of the base URI in those files already. If we provide anything for download I think it should just be the "compiled" 223 ontology all in a single file.

[lazlop]

Yes, these should just link to data.ashrae.org.

I think the 223p-all file should be included, but currently each of the files is declared an ontology with it's own file location at data.ashrae.org (e.g.: <http://data.ashrae.org/standard223/1.0/inference/model-rules>).

@steveraysteveray are the separate file locations on data.ashrae.org just an artifact of development?

[steveraysteveray]

I don't think of the separation of files as an artifact of development, but rather a sensible way of organizing for future maintenance. I don't have a problem with mashing them all together for the computer to ingest it all when using them, and that's what Gabe's code does, including the removal of all but one of the ontology declarations. So for distribution/execution, no problem. For archiving and maintenance, I think we should keep them separate.

[MatthewSteen]

For the initial Reference files, I've settled on these two files/pages. We may want to break the Other Resources up if it becomes too long.

I think each of these should have an "owner" to go through them to finalize the content and a dedicated issue and PR to address them (with a review by a team member).

1. Open223 Resources
   • models.open223.info
   • explore.open223.info
   • query.open223.info
   • defs.open223.info
2. Other Resources
   • Python libraries
   • Bob
   • BuildingMOTIF

FYI @pdelgosha22

[lazlop]

@MatthewSteen @steveraysteveray @gtfierro

Should there be a page for ASHRAE resources which would be the ontology and publication document?

[MatthewSteen]

Yes there probably should be eventually...once links actually work. The primary one would probably data.ashrae.org. These could also go into the intro.md landing/root page.

• Link to current public review document.
• Link to any supporting files.
• ?

Personally, I think development should completely move to GitHUB instead of GitLAB, or at least public GitLAB, which may be easier from Cornell's enterprise instance.