Discussion on the term-template

[RieksJ]

Here is a first proposal for a Term-Template that people might use to document a term. This issue aims to discuss what a template for terms should look like.

[dhh1128]

Some meditations about the current template and the sample entries that @RieksJ created in some of the terms repos:

1. Rieks capitalized the page names (e.g., the page that holds an entry for "agent" is named "Agent"). I believe this will be the natural tendency of wiki-based collaborators, but I think it's a mistake. The reason is that it hides the distinction between terms that require a particular case and terms that allow a particular case. An acronym like "GDPR" and a proper noun like "Good Health Pass Collaborative" don't allow lower case, but a term like "agent" can be capitalized or not, depending on where it appears in a sentence or title. Thus, capitalizing terms just to obey conventions like the ones English teachers taught us ("Capitalize the first letter of every major word in a title") -- or capitalizing them the way lawyers do ("Capitalize every term that's defined in the contract") is actually lossy insofar as our corpus is concerned. This is discussed here; I recommend we never capitalize a term for wiki appearance reasons, but rather capitalize only terms that require it, and use lower case everywhere else. (The template as written currently encourages this choice, but we could change that if we end up going a different direction.)

2. Should we consider a "See Also" field that is separate from the running text of a definition? (This would not preclude running text that refers people to other places, but it would be a general way to link related content without a lot of precision -- you'd get synonyms, antonyms, cover terms, narrower terms, older-and-now-deprecated terms, etc. Not sure if that's a good thing.) In at least one example that Rieks created, "Related Concepts" was used for this. That field name feels fine to me as well, if we like the idea.

3. Here, we have a field named "Criterion." I think this field is useful, but in some cases, I think there will be more than one of them, so I suggest that the field be named "Criteria" instead -- and that it consist of a bulleted list of criteria. If we only have one criterion, so be it -- but I don't think we should rename the field in that case. It would just make maintenance (as criteria get added and substracted) and the export tooling more complicated.

[dhh1128]

4. We have both "Examples" and "Usage Examples." One is intended to be examples of the concept, and the other is intended to be examples of the term appearing in a larger sentence or paragraph of text. Do we want both? If yes, let's name them differently enough that they're not confused.

5. We need an attribution convention, and I think our template ought to illustrate it. See [PROCESS] ToIP in violation of the Sovrin Glossary CC BY-SA section 3. Attribution requirements #47 and need a convention for attribution #54

[RieksJ]

The most minimalistic term-template I can think of has the ## Definition section and the ## Tags section, as currently specified in the Term-Template.

I specifically like the idea of specifying that the first sentence of the definition SHOULD be useable as a hovertext (i.e. a text that would be shown in a popup/popover balloon in an HTML-rendering of a document that refers to this term), as it fits nicely with my eSSIF-Lab terminology experiments.

Note however that a hovertext is not a text that generically qualifies as an entry for a glossary (as an example, texts such as in the Sovrin glossary or GHP glossary are way to elaborate to serve as a hovertext). Things like this may be discussed in #53.

I suggest we reserve a set of header texts which we may want or need (at some point in time) for the purpose of ingesting into the corpus. Definition is already one of them, and Examples may be another, but I expect we will be wanting/needing more as we learn our way in this new arena, and we also need to properly specify what should (not) go in such sections.

[RieksJ]

@dhh1128 noted that capitalization of page names (as I habitually do) is actually wrong, and provides reasons for his position that I underwrite. However, there are (rare?) cases that the opposite occurs: eSSIF-Lab, for example, starts with a lower case character (as opposed to GDPR that starts with upper case). I wonder if there are more examples, or if eSSIF-Lab is just a quirck

[RieksJ]

I would like to note that the term template provides a means :

• to define/describe a concept (not: a term)
• to associate a term with it, which presumably is the default name that is used within the scope to refer to the described concept.

We may also need another kind of term template, i.e. one that provides a means:

• to refer to a concept (rather than describe it), which could be within the same scope, or in some other scope
• to associate a term/name with it, which would then be used within the scope to refer to the referenced concept.

Doing this allows a scope

• to define aliases for a concept they defined
• to use their own name for a concept defined in another scope (even if that name is the same as the default name that is used for that concept in this other scope).

Perhaps we might want to register a header ## Reference (or something similar) and have some syntax that allows us to refer to the meaning that the term will be assigned.

[dhh1128]

There is a tension between the sophisticated type of data that reeks is advocating, and the relatively simple mental model that many people will have as they edit wiki‘s. The template that we chose deliberately sided with simplicity over sophistication. We are going to re-create the entire internal data model if we go down the road of splitting terms and concepts apart. However, we may want to do that in a few specialized cases. It may be desirable, Rather than creating a second template type which normalizes this advanced usage, to annotate the existing, simple template with a link to instructions about how to do more sophisticated things.

[RieksJ]

Rereading my earlier contribution I can see that this confuses readers. I do not intend to recreate the entire internal data model. I do think though we should remain focused on the purpose of having these wiki-pages, which is that they serve as a very easy means for people to contribute to various terminologies in the corpus. Wiki pages will get processed (ingested into the corpus as follows):

• processing the title of the wiki page results in the creation of a term-record in the internal data model.
• processing the ## definition section creates a concept-record, and a link in the just created term-record to that concept-record.
• processing other sections, e.g. ## example will create other records insofar that is defined, and otherwise ignored.
• processing the ## tags section creates .... (whatever it is).

I only propose to extend this as follows:

• allow users to replace the ## definition section with a ## reference section that contains a single reference to a concept of some (other, or the same) scope.
• to process a ## reference section by linking the just created term-record to the concept-record referenced by the contents of that section.

This should not need another template, we can just extend the current one.