Meeting Date
Zoom Meeting Link / Recording
Attendees
Main Goal of this Meeting
Review our progress on the ToIP Term Tool and agree on next steps for putting the ToIP Core terms wiki into production.
Agenda Items and Notes (including all relevant links)
| Time | Agenda Item | Lead | Notes |
| 5 min | - Start recording
- Welcome & antitrust notice
- Introduction of new members
- Agenda review
| Chairs | - Antitrust Policy Notice: Attendees are reminded to adhere to the meeting agenda and not participate in activities prohibited under antitrust and competition laws. Only members of ToIP who have signed the necessary agreements are permitted to participate in this activity beyond an observer role.
- New Members: None.
|
| 5 min | Review of previous action items | Chairs | - ACTION: Rieks Joosten and Daniel Hardman to arrange a meeting to discuss how this hyperlinking should work with ToIP Term Tool V1 and our current terms wikis.
- ACTION: Rieks to incorporate feedback and publish revisions to his mental model diagram for the relationship of CTWG terminology and ToIP terminology.
- ACTION: ALL to review and comment on Rieks' draft proposal defining the objectives, ingestion policies, and curation policies for the ToIP terms community.
- ACTION: ALL to review the ISO Guide to IT Terminology.
- Rieks noted that it highlights the same challenges we are dealing with the CTWG, so it is not essential to read but helpful.
|
| 5 min | Update on hyperlinking format discussion | | Report on the outcome of the first action item above. - Daniel Hardman reported that Rieks Joosten came up with a proposed format for how hyperlinking can work both inside and outside a particular community.
- The format is
[showtext](term@scope) where:showtext is the text displayed in the document.term is the glossary term.@scope is how to reference the scope of a glossary using the tag for that glossary.
- If an author uses this convention now, it will be a broken hyperlink until the ToIP Term Tool is updated to support it.
- So the conclusion was that we will adopt the convention as soon as the ToIP Term Tool supports it (ideally in V2).
- Rieks added that this is not yet the highest priority, but that we will work towards it.
- He pointed out that hyperlinks in documents should be to terms in a glossary, not to terms in a terms wiki which are dynamic. This will be less of a maintenance burden because the glossary will have been curated, vs. the terms wiki content which is intended to be ingested.
|
| 5 min | Update on ToIP Term Tool progress | Daniel Hardman | Daniel reported that he has finished the glossary term selection ("tagged subsets") feature for the ToIP Term Tool V1. This is in addition to what he reported in Slack: - I have turned on glossary publication for the
toip repo and the ctwg repo. This means our first two glossaries are live (published). You can see the results here: - The actions that build these glossaries are one-click, but they need to be manually re-run for now; they don’t automatically run when a wiki page is updated. That’s a future enhancement. (@Rieks Joosten: I remember that we wanted to rename these repos, removing the “-terms” part of the name. I haven’t done that yet, but it will be trivial as soon as the CTWG approves.)
- The process I used to do this work is documented here:
- I think we need to move this documentation somewhere else, but I can’t remember where off the top of my head, and I’m now off to other tasks for a while. Feel free to move yourself — or I’ll come back and do it when I remember.
ACTION: Drummond Reed to determine where to move Daniel Hardman's documentation of how to use the ToIP Term Tool. In summary, with this set of features, ToIP Term Tool V1 is complete, and we can begin to discuss the features we would like to add for V2. - Rieks added that one danger that he's concerned about is that communities will start to use the terms wikis but that they are not the actual corpus that can be curated. So we still have work to do to form the full corpus that can be curated.
- Scott Perry shared that we need each WG deliverable to starting documenting their terms in a terms wiki, and that each ToIP WG should have a member of this WG so that we are all working together on terminology.
- Rieks felt that in addition to having multiple WGs contribute members to the CTWG, we also want to support decentralized curation.
Daniel then showed us a demo of how to use some features of the ToIP Term Tool: - He showed how the glossary author can control the template for the glossary document.
- He also demonstrated how a glossary can now be updated automatically when changes are made to a page on the terms wiki.
- Nicky Hickman showed an example of how she is using the terms wiki for YOMA.
- Daniel explained that if an author wants to use the ideal form, the links won't work But in the short term, we need to use a form like this, where each term is appended to the base URL for the terms wiki glossary with a fragment.
|
| Naming of terms wiki repos | All | We discussed the prospect of having each repo name end with the tag name for that repo. So instead of .../ctwg-terms/glossary.html, we could use .../ctwg/glossary.html. - We agreed that we don't want to make it a hard requirement that all terms wiki repos must be named with the tag for their scope.
- That said, we also agreed that it would be ideal if the terms wiki repo name corresponded to the tag for the scope.
- DECISION: It is RECOMMENDED that terms wiki repos be named with the tag for their scope. When this is not possible, a terms wiki MUST be able to be mapped its tag to the terms wiki repo URL using an entry in the Tags section of the home page of the terms wiki. This SHOULD be a ToIP Term Tool V2 feature.
|
| Discussion of the role of mental models | All | Rieks clarified that mental models are patterns of coherence of concepts that work together. We talked about how to best reference the terms from eSSIF-Lab mental models. |
| 15 min | Decision on ToIP Core terms wiki process | All | See the ToIP Core Terminology Management Process section of the ToIP Core terms wiki README.md. The following is a summary of notes copies from the Slack discussion between Rieks and Daniel. We ran out of time to complete this discussion, so we will need to continue it in Slack. Rieks Joosten proposal (from our Slack channel): I suggest that we enable toip-groups to add terminology stuff to their existing repo's, requiring them to: - specify a location (URL) where they publish (rendered) documents (papers, documentation, ...), by default at
trustoverip.github.io/reponame, which would include trustoverip.github.io/reponame/glossary for its (rendered) glossary. This allows people to quickly find stuff, and authors of GDocs, Confluence pages and the like will have stable URLs to link to. We should start out by ONLY using the default location. - specify a location where they maintain the 'raw docs' from which they render the stuff, by default at
github.com/trustoverip/reponame/docs. This allows people to contribute to the groups documents by means of issues and pull requests to the repo. We should start out by ONLY using the default location. - specify a location where they curate their terminology, from which they produce their 'raw glossary' (putting the result in the 'docs' folder, which is subsequently rendered and published as a usable glossary), by default in the subdirectory
docs/terms of the repo. This allows people to contribute to the group's terminology by means of issues and pull requests. We should start out by ONLY using the default location. - consider using the wiki of the repo as a terms-wiki like we do now.
- consider some practical conventions for facilitating group members to contribute to the development of their terminology, e.g. by making specific issue-labels and/or templates. This would be (near-)future work.
- read the documents (such as which you are drafting) that support repo admins in doing terminology. Of course, the 'raw text' would then reside at github.com/trustoverip/ctwg/docs, and it would be viewable at trustoverip.github.io/ctwg/doc-id. That would be the link that could be linked to from confluence pages, GDocs, etc.
Daniel Hardman's counter-proposal: - Rename the current repos that have
-terms in their name into the name without that suffix: ctwg-terms becomes ctwg, for example. This would mean we would have a glossary published at https://trustoverip.github.io/ctwg/glossary.html. A permalink. I am in favor of this proposal but want the WG to ratify it. An analogous URL, with a different group name, would be the canonical location for any group within TOIP. - Accept the limitation that the glossary URL has to end in .html.
- Implement your suggestions 1 and 2 and 5 and 6 as written.
- Unlike your #4, require a terms wiki. We have no tooling that supports anything else, and we have no plans to produce any such tooling.
Daniel adds: I have now enabled automatic glossary generation on terms wiki edit, so any time someone changes a page in the terms wiki for either of the active repos, the glossary is automatically rebuilt (on about a 60-second delay). |
| 10 min | Review Rieks' updated mental model for Terminology | Rieks Joosten | See the Terminology Pattern on the eSSIF-Lab site. The mental model diagram is also copied below as #1. The text also refers to the (updated) Notations and Conventions and also explains why the full text of the formal definitions are needed because the diagram cannot convey several key aspects. - Drummond Reed had a question as to whether "terms community" is needed or whether "community" by itself would be sufficient.
- Rieks explained why "terms community" was indeed needed as a specialization of "community".
- Drummond was completely satisfied with Rieks' explanation and supportive of the model.
|
| 5 mins | - Review decisions/action items
- Plan for next meeting
| Drummond Reed | By the end of the meeting, Daniel Hardman had implemented our decision above, renamed the applicable terms wiki repos, and turned on their glossary functions. We now have five operational terms wikis: - CTWG: https://github.com/trustoverip/ctwg/wiki
- ToIP Core: https://github.com/trustoverip/toip/wiki
- YOMA: https://github.com/trustoverip/yoma/wiki
- eSSIF-Lab: https://github.com/trustoverip/essiflab/wiki
- ACDC: https://github.com/trustoverip/acdc/wiki
Our focus now needs to move to documenting how each of these groups can put these terms wikis into full production. Rieks also wants to start producing requirements for the ToIP Term Tool V2. ACTION: Drummond Reed to contact Judith Fleenor to confirm that the $20K bounty is still available to put towards ToIP Term Tool V2. |
Screenshots/Diagrams (numbered for reference in notes above)
#1 — eSSIF-Lab Terminology Pattern. We use the following notations and conventions.
The figure itself is not a complete representation of the model - the texts in the section 'formalized model' must also be considered. One of the reasons is that some constraints of the formalized model cannot be represented in the figure. Here are two exmples:
- "A term that is part of a given scope refers to precisely one definition and the single concept that this definition defines." So a single term can refer to different definitions/concepts, but only within different scopes. Within a scope, there is no ambiguity of terms.
- "If a definition is part of a scope, then there is a terminology that is part of that scope, and it contains a term that refers to this definition". Loosely rephrased: "All definitions in a scope are part of its terminology". And consequently: additional terms may exist in a terminology that refer to definitions outside the scope (as well as within the scope, e.g. enabling aliasing for its own definitions).
Decisions
- DECISION: It is RECOMMENDED that terms wiki repos be named with the tag for their scope. When this is not possible, a terms wiki MUST be able to be mapped its tag to the terms wiki repo URL using an entry in the Tags section of the home page of the terms wiki. This SHOULD be a ToIP Term Tool V2 feature.
Action Items
