How to release the Target Model (TM)

[VladimirAlexiev]

Hi @stephenhart8 and @illip , I work with CHIN (currently on Nomenclature) and was delighted to find this project.

• where is the TM mentioned in many issues? Is it available for inspection?
• does the group have a defined policy toward linked-art? I have not found issues linking to that repo

[illip]

Hi @VladimirAlexiev, has mentioned by email, CHIN is aware that it's difficult to comment our issues without the TM documentation.

Please be assured that CHIN will do whatever is necessary to find the best way to release this documentation as soon as possible. An update will be made here when it is done.

[VladimirAlexiev]

@illip I think you mentioned it can't be released before it's fully translated to EN and FR?

Then how do you guys plan to maintain the translation (cc @stephenhart8)? The best would be if you have some externalized strings (same problem now faced by Nomenclature SPARQL UI) and have some infrastructure that can generate EN & FR renditions from the same intellectual content.

Otherwise it'll be very hard to evolve the models.

[illip]

@VladimirAlexiev We have been authorized to share a working version of our model without it being translated. This is good news!

However, I'm still interested to know how you would tackle these "EN & FR renditions of the same intellectual content". Do you have a specific tool in mind? If it's something we can easily generate; we might be interested.

In addition to this translation question, I would like to keep this discussion opened in order to explore the best way to release our model. For the moment, I have three options in mind:

1. Keep our model documentation on Google Drive, as it is currently, and provide the "read-only" link on GitHub. This is probably the simplest way of doing it. So all the comments on the model would be done through GitHub issues, @stephenhart8 and I think it's a better practice to use GitHub issues instead of Google Docs comments; at least it's easier to manage. However, we don't know if this is going to be too complicated for content experts who are used to comment in Google Docs. Also, if at some point we would like to push the model on a website, it might be more difficult to dynamically integrate the content.

2. We migrate our model on Github using different Markdown files like SARI (https://github.com/swiss-art-research-net/reference-data-models). That way, it would be easy to push our content directly on webpages through Github Pages. I think it will take time to move everything but when it's done, it will clearly be easier to manage everything in one place. For the content experts, I don't think it's more complicated to explore a bunch of Markdown files than a Google Doc. Also, the versioning is clearly better handled (at least more options) in GitHub than Google Docs.

3. If there is a strong desire to give content experts the right to edit the Google Doc, we could keep option 1, but with "suggesting" access. However, it might become difficult to keep the Google Docs comments aligned with the issues.

I don't think it's a good idea to change the way we publish our model when it will be already online. In my opinion, it's important to assess and decide which option is the best on the long-term. Especially, which one is the best to build other features on top of it afterwards?

Do you have other options in mind? Comments?

If you don't mind, I will change the issue title accordingly.

[stephenhart8]

My preferred option is 2. We would have everything pertaining to the model in one place and would be easier to manage. My only concern is about the draw.io for the diagrams of the patterns that are for the moment embedded in the Google Doc, allowing modifications without much problems. Would it be possible to have something similar to GitHub?

As @illip stated, we need to think before choosing, as it is quite a time-consuming task to migrate the documentation from one platform to another.

[Habennin]

Hi all,

Regarding the documentation, the SARI documentation currently references draw.io diagrams from the markdown, so that is possible.

That being said, we are trying to consider ways to streamline the means of generating the documentation as presently it requires many different places to enter the same data leading inevitably to technical mistakes in documentation that should not exist but are easy to make and miss when reviewing.

Our discussion is on-going and we are trying to widen the field of possible answers. One tool under consideration is mermaid: https://mermaid-js.github.io/mermaid/#/ which is adopted by Linked.Art. This would allow the diagram documentation to be generated automatically at least. In Linked.Art Rob has gone further and generated code to create examples presented in different formats. This is very nice and useful as a feature for adopters. It has a technical drawback for a modeller (from my point of view) in that you must always present the model with an example, when one would prefer to have one presentation of the model as such and then another presentation with the example.

Anyhow, happy to open this discussion wider and bring in more ideas from the community.

I would agree, only switch your documentation format once you are sure you want to go in that new direction!

[VladimirAlexiev]

I think diagram generation is a must in order to be able to evolve the model more easily, and have a guarantee that the diagrams are correct. The best is to generate the diagrams from formal examples.

My rdfpuml tool generates diagrams using plantuml (similar to Mermaid but a lot more powerful) from actual RDF. Also, they are a lot more compact than the linked.art examples, which allows the modeler to tackle bigger patterns and express them intelligibly. The diagrams are a bit plain (yellowish) but I had plans to extend with icons and colors (like all other layout details, controlled with extra puml: triples). Using actual RDF has these benefits:

• turtle is easy to write and is universally known to RDF modelers
• can be validated with RDF tools
• expresses important details such as URL patterns

In contrast, AFAIK linked.art examples are written as pytonish object instances using a tool called Cromulent.

After all, it's a matter of habit, convenience and personal preference. What's important is to guarantee consistency.

---

EN vs FR: again it's important to guarantee consistency. The organization of the translation effort will depend on how modular or structured is your content. I would look at tools and approaches for translating websites (eg a w3c standard for marking translatable content is ITS) or large texts (like Translation Memories, which ensure consistent use of terminology)

[illip]

Hi all,

For the moment, we will breakdown our Google doc in several .md files to have everything on GitHub. This looks like a low risk transition since it seems quite convenient to work with .md files if we decide to push everything on a "real" website in a near future.

About the schemas, we haven't decided yet which option to use but Draw.io is clearly not the best solution (visually nice one though, but it's a lot of work). For the moment, we will include our draw.io .jpeg export to our .md files but we are looking for a better integrated solution.

CHIN would be happy to continue the discussion about the best way to document semantic models with the community. What would be the best channel for that?

[illip]

Quick update regarding our last decision

We will use embedded iframe exports that can be generated directly from Draw.io. Two benefits:

1. We don't have to upload our images somewhere and avoid some steps.
2. If we edit a diagram on Draw.io, it will automatically be updated in our doc.

[illip]

The Target Model is available on GitHub Pages and the Draw.io diagrams are embedded with iframe.