2021-03-01 CTWG Meeting Notes

Meeting Date

• 01 Mar 2021 

Attendees

• Drummond Reed
• Rieks Joosten
• Daniel Hardman
• Dan Gisolfi
• Maria Iliadi (GRNET)
• Foteinos Mergoupis-Anagnou
• Brian Dill

Main Goal of this Meeting:

Ensure we have alignment on how we will move Docusaurus Terminology V1 into production and discuss the features we would like to see in V2.

Agenda 

Recording

• Link

Presentation(s)

• none

Documents

• TEv2 requirements/suggestions (based on experiments in eSSIF-Lab)

Notes

1. New members
2. "Two mental model" explanation & discussion — Daniel Hardman
   1. See slide #1 below
   2. The left side is the standard worldview of Docusaurus Terminology that the overall goal is to build a documentation website that includes terms and thus one part of the website is a glossary
   3. The right side represents the objectives of the CTWG to manage terms that may exist in multiple glossaries that in turn may be used in multiple artifacts, of which a website of some kind might be one instance.
   4. Daniel did not want to make too much of this distinction, but felt it was important when discussing the evolution of the Docusaurus Terminology tooling.
   5. Maria said she basically understood the picture on the right, and the need for Docusaurus Terminology may need to support multiple artifacts.
   6. Rieks Joosten said he understands the two perspectives. He believes we can look at the Docusaurus Terminology tools as a transformation tool. The final current step in the transformation is currently outputting a website, but it can be modified to produce others.
   7. Daniel agreed that he believes as we evolved Docusaurus Terminology, it will likely end out supporting both worldviews.
3. Demo of the work over the past two weeks — Daniel Hardman — see slides #2 - 4 below
   1. He first created a temporary repo called CTWG Sandbox
   2. It included the white paper called Decentralized SSI Governance for the purposes of showing how Docusaurus Terminology could be used for modeling our whole process.
   3. Rieks converted the Google doc into a Markdown document with all the necessary markup.
   4. Rieks also submitted the Markdown files providing the definitions for each term used in the white paper. 
   5. The result is at trustoverip.github.io/ctwg-sandbox/decentralized-ssi-governance.
   6. Daniel showed the Javascript that controls the steps in scripting the Docusaurus Terminology process for producing the final output.
   7. To repeat the process for a new document:
      1. Go to the repo (or create a new one)
      2. Create a directory for the glossary to live
      3. Decide on the output (e.g., a website)
      4. Check in a directory with all of the terms in Markdown
      5. Set up a GitHub Action to republish the glossary with any changes to the repo
      6. It can be easier to set up a new document and glossary incrementally, vs. a large document.
   8. Dan Gisolfi asked if a term can be used in more than one repo
      1. Daniel Hardman explained that today, the glossary lives inside a single repo, so all terms are together in one place.
      2. The only other option is to replicate the terms file.
      3. We agreed that it would be ideal if an overall terminology corpus—such as the one the CTWG is reponsible for maintaining on behalf of the ToIP community—could be shared across many individual projects/stakeholders/scopes—such as the Working Groups at ToIP.
      4. If each WG was able to maintain their own definition of a term (when necessary) in their scope, but viewers could see all the definitions for that term in the corpus, that would be ideal.
4. Moving Docusaurus Terminology V1 into production
   1. Drummond asked about how we would share terms across multiple documents—for example for 10 different deliverables
   2. Foteinos asked what the different glossaries would be for—would they be subsets of the same overall glossary (or "terminology corpus")
   3. Daniel Hardman explained that the same term could appear in more than one glossary with different definitions depending on context.
   4. Foteinos suggested that terms could be exposed as JSON objects via an API. They could be called with an associated scope.
   5. Rieks Joosten used slide #5 below to illustrate the idea that the same term can have a different meaning in separate groups or contexts.
   6. Marie asked about the point of control for the common repository and how access permissions would be managed.
   7. Daniel Hardman proposed an answer to Maria's question based on slide #6.
      1. The Produce step produces output that is suitable to be processed for rendering but is not actually rendered (that is step 4).
      2. Daniel explained that Docusaurus Terminology currently goes from the Curate step to the Process step, skipping the Produce step.
      3. Daniel said that if the next version of Docusaurus Terminology could add the Produce step. That way we could Produce in all types of outputs.
5. CTWG requirements for Docusaurus Terminology V2
   1. We talked about a new pattern for the next version: 

      1. [foo](/docs/terms/foo)

   2. Drummond suggested that if the reference to the term included the scope, then the term would be able to be mapped to multiple definitions depending on scope.

      1. This could take the form of either of the following:

         1. [foo](/docs/terms/scope/foo)
            [foo](/docs/terms/foo/scope)

   3. Rieks talked about making the format as technology agnostic as possible. Drummond agreed.
6. Review of Decisions and Action Items
   1. Rieks agreed to update our wiki page on Specification for Creating and Using Terms
   2. Drummond will post proposed next steps in our Slack channel
7. Next meeting — same time in two weeks

Slides

#1 from Daniel Hardman

#2

#3

#4 - Markdown document defining a term

#5 - Rieks picture of multiple related groups. The same term could appear in each group, and the definition could be different in each group. 

#6: Daniel's slide showing the proposed stages for managing the underlying data. 

#7: The Markdown file for defining a term

Decisions

• The V2 version of Docusaurus Terminology should include the ability to maintain the terms for multiple documents and projects in one shared terminology corpus, with each term being able to have multiple definitions that are disambiguated by a scope or group

Action Items

• Rieks Joosten will update our wiki page on Specification for Creating and Using Terms to capture our conclusions from today's meeting
• Drummond Reed will post proposed next steps in our Slack channel