Commit bc70a51b authored by Rieks Joosten's avatar Rieks Joosten
Browse files

remove the docs/terminology directory as we do not use/need its contents

parent 7aba486f
# README for terminology-related files.
:::info
under construction
:::
This document states the requirements for files in this directory, such that they can properly processed into useful and usable Docusaurus documentation.
## Filenames
All file MUST have the structure: `<scopeid>-<type>-<instanceid>.mdx`, where
- `<scopeid>` is the (all lowercase) identifier of an existing scope, i.e. the file `<scopeid>-1-scope.mdx` must exist.
- `<type>` MUST be any of the following:
- `scope`
- `pattern`
- `concept`
- `term`
- `glossary`
- `<instanceid>` MUST be a lowercase identifier that only uses characters `a`-`z` and `-`.
## Templates
The `terminology/templates` directory contains templates for each of the types. A template file has comments that hold, amongst others, requirements for the contents of instances of that template.
## Referring to terms in documentation files
Any term can be referred to in any documentation file, using the syntax `%%<termref>%%`, where `<termref>` is either the `<conceptid>` of a concept
- `<sometext>` is a text that will be displayed as if it were a term
---
id: essifLab-concept-party
title: "Concept: Party (Scope: eSSIF-Lab)"
scopeid: essifLab
termid: party
hoverText: "Entity that has knowledge about what exists, ways to reason with that knowledge, and ways for making decisions in a Self-Sovereign fashion."
---
## Criterion:
Entity that has knowledge about what exists, ways to reason[^1] with that knowledge, and ways for making decisions in a Self-Sovereign[^2] fashion.
## Examples:
People obviously qualify. Enterprises, governments, and other organizations also qualify as they can be seen as having their own knowledge (e.g. in their registrations, databases etc.), ways to reason with that knowledge (business rules, exercised by their employees or IT systems), and making decision.
Stones, pictures, ideas, etc. do not qualify. Also, electronic components do not qualify[^3].
### xxx:
to be elaborated
---
[^1]: Reasoning means: inferring conclusions from data, regardless of the kind of logic that is being used, or whether the reasoning is coherent, or consistent.
[^2]: This means that the party can do this all by itself. For humans, the rights for this are laid down e.g. in the [ECHR](https://www.echr.coe.int "European Convention of Human Rights") ([ECHR articles 9-11](https://www.echr.coe.int/Documents/Convention_ENG.pdf))
[^3]: While the case can be made that (some) electronic components can reason, they do not do so in a self-sovereign fashion as intended by this definition. We do not want to discuss AI-equipment here.
---
id: glossary-essiflab
title: Glossary eSSIF-Lab (Scope essiflab)
---
<!--A glossary is a list of terms with (short) explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s).-->
## Purpose
<!--State the purpose(s) that this glossary aims to fulfill, in such a way that readers can easily determine whether or not it is useful for them to use it.-->
This glossary lists the basic concepts that are needed by the various stakeholders within the eSSIF-Lab project, ranging from governance, business, process, technology etc. The idea is that it defines at least the set of concepts that are often used in these varied domains, allowing a reader with a specific background to learn how the concept is used from other (valid) perspectives that may be alien to him/her.
## Sources
<!--Here, the sources should be identified from which the glossary entries (and their descriptions) are to be collected-->
### Include
<!--Specify the %%scope-files|scope-file%% that are to serve as a source for this glossary-->
* eSSIF-Lab
### Terms
<!--Specify the %%term-files|term-file%% that are to serve as a source for this glossary. If a term is defined in a scope as well as in a %%term-file%%, the latter takes precedence.-->
### Patterns
<!--Specify the %%pattern-files|pattern-file%% that are to serve as a source for this glossary. If a term is defined in a scope or as a term as well as in a %%pattern-file%%, the latter takes precedence.-->
### Concepts
<!--Specify the %%concept-files|concept-file%% that are to serve as a source for this glossary. If a term is defined in a scope, or as a term, or in a pattern as well as in a %%concept-file%%, the latter takes precedence.-->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
---
id: glossary
title: "Glossary (Concept)"
scopeid: essifLabTerminology
type: concept
typeid: glossary
hoverText: "an alphabetically sorted list of terms explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s)."
---
## Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
A glossary is an alphabetically sorted list of terms and explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s). However, a glossary may also be created for the purpose of being included in other glossaries (as a construction aid to such glossaries), or for still other purposes.
## Purpose
<!--Describe why the concept is needed. What purposes does it serve? What can you do with it that you cannot do (as well) without it? What objectives does it help realize? Why is this conceptevant within its scope of definition?-->
A glossary may serve various purposes, the most important one of which would be to help people understand texts around a certain (set of) topic(s) in some context(s).
## Criteria
<!--REQUIRED--How is this concept different from related ideas? What are essential characteristics that must be true? This is where you specify the [intensional definition](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions) of the concept, i.e. the necessary and sufficient conditions for when the term should be used. This makes that the conceptomes crystal clear. In the case of nouns, this is equivalent to specifying the properties that an object needs to have in order to be counted as a referent of the term.-->
an alphabetical list of words or phrases with (short) explanations, that exists for the purpose of helping people to get a first understanding of the meaning of each word in the scope/context for which the glossary is created.
## Examples
<!--This (optional) section contains examples, both of what satisfies the definition (and hence qualifies as an instance of Glossary), ans what does not. If you can think of examples for which the criterion may not (always) work, then describe them, too, and inform the reader why this hasn't affected the definition (yet) - e.g. because such cases are irrelevant to the scope within which the term is defined.-->
Examples include the [eSSIF-Lab Glossary](essifLab-glossary), the [Sovrin Glossary](https://sovrin.org/library/glossary/), the [Glossary of Internet Terms](https://www.internetsociety.org/internet/glossary-internet-terms/), and glossaries for Legal Terms, e.g. of the [US](https://www.uscourts.gov/glossary), [Singapore](https://www.supremecourt.gov.sg/services/self-help-services/glossary-of-terms), the [UK](https://www.copfs.gov.uk/involved-in-a-case/glossary-of-legal-terms).
## Related Concepts
<!--This (optional) section lists words/phrases that are encountered in other contexts that have the same or a sufficiently similar meaning as Glossary. In this section you may point out the (subtle) differences between Glossary and this related terminology. This helps readers better/deeper understand Glossary, and how it may be used to relate to existing texts. Ideally, such references are accompanied with links to (preferredly authoritative) sources.-->
- Dictionary - this is more extensive; it usually includes multiple meanings of words, and may include additional information e.g. on pronunciation, etymology, usage, example sentences,synonyms, etc. See [askdifference.com](https://www.askdifference.com/dictionary-vs-glossary/)
- Vocabulary - this is a body of words used in a particular language or field of expertise. A Glossary can provide the meaning of each word for use within the scope(s) for which the Glossary is created.
## Notes
<!--This (optional) section is the place to put anything for which there is no other good place to put it.-->
The [eSSIF-Lab Glossary](essifLab-glossary) contains the words that are defined within the scope of the [eSSIF-Lab framework](introduction).
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
---
id: term
title: "Term (Scope: essifLabTerminology)"
scopeid: essifLabTerminology
type: concept
typeid: term
hoverText: "a word or phrase that is used in at least one scope/context to refer to a specific concept."
---
## Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
A Term is a word or phrase that is used in at least one context (and/or for specific purposes) to refer to a specific %%concept|concept%%. As a concequence:
- the meaning of a Term may vary across contexts. For example, in the context of a buty-salon, the term 'nail' has a different meaning than in the context of constructing buildings.
- different terms (in different contexts) may refer to the same concept ([synonymity](https://en.wikipedia.org/wiki/Synonym)).
## Purpose
<!--Describe why the concept is needed. What purposes does it serve? What can you do with it that you cannot do (as well) without it? What objectives does it help realize? Why is this conceptevant within its scope of definition?-->
Understanding words or phrases uttered by others requires that we are able to 'translate' them terms into terms that we habitually use. While this is mostly an automatism, and it often is not necessary to be all that precise, this may be different when they relate to stuff we find important. The ability to refer to a specific concept with a specific text or phrase, where this 'linking' is limited to a specific (or several) context(s) helps us to better interpret the intentsion of what others convey in spoken or written language.
## Criteria
<!--How is this concept different from related ideas? What are essential characteristics that must be true? This is where you specify the [intensional definition](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions) of the concept, i.e. the necessary and sufficient conditions for when the term should be used. This makes that the conceptomes crystal clear. In the case of nouns, this is equivalent to specifying the properties that an object needs to have in order to be counted as a referent of the term.-->
A Term MUST be a word or phrase that is linked to at least one %%context|scope%% and refers to precisely one %%concept|concept%%.
## Examples
<!--Provide a few sentences in which you give examples that obviously qualify as instances of `Term`, and that do NOT obviously qualify. Also, provide examples that are not (so) obvious, but help users to better understand its intension.-->
## Related Concepts
<!--Link to any %%concepts|concept%% that are similar but distinct, with a note about the relationship.-->
## Domains
<!--In which general knowledge ecosystems or mental model families does this concepty a role?-->
* eSSIF-Lab
* ToIP
* Sovrin
* DIF
* NIST
* ...
## Tags
<!--Add hash tags here that allow us to group concepts in useful ways.-->
* Terminology
## Use-cases
<!--This (optional) section specifies an (optional) introductory paragraph, and a level-3 (i.e. `###`) subsection for every use case it describes. Every such use-case SHOULD
- describe the situation/context of the use-case;
- show how to apply ``Term`` to/in that situation;
- shows the relevance of having ``Term`` for the use-case as opposed to not having it.-->
## Notes
<!--This (optional) section is the place to put anything for which there is no other good place to put it.-->
There is an important [distinction](https://simple.wikipedia.org/wiki/Concept) between concepts and the (multitude of) terms (names, labels) that we need to be able to talk and reason (argue) about them. Please consider that
* different terms are used in different contexts for the same concept
* in different contexts, a single term may refer to different concepts
* to resolve terminological disputes, which usually are about the 'correct' meaning of a term, try to establish the criteria that the different participants use for the concept behind the term. That helps participants understand each others (different) positions, and provides a better basis for resolving the conflict.
---
## Footnotes
<!--This (optional) section contains any footnotes that may have been specified in the text above.-->
[^1]: WikiPedia has a concise [explanation of concepts](https://en.wikipedia.org/wiki/Concept). We use the term 'concept' as a [mental representation](https://en.wikipedia.org/wiki/Mental_representation).
[^2]: For the difference between 'Concept' and 'Term', see https://simple.wikipedia.org/wiki/Concept.
---
id: pattern-mental-model
title: "Pattern: Mental Models (Scope: essifLabTerminology)"
scopeid: essifLabTerminology
type: pattern
typeid: mental-model
hoverText: "This pattern captures the foundational concepts and relations that we need for creating, maintaining and using (decentralized) vocabularies (terminologies) that groups of people can use for the specific purposes they pursue."
---
## Purpose
<!--Concisely describe what can you do with the pattern that is (at least) harder if you didn't have it.-->
This pattern captures the foundational concepts and relations that we need for creating, maintaining and using vocabularies (terminologies) that groups of people can use for the specific purposes they pursue. Alternatively, we need these concepts to allow people to use 'decentralized vocabularies' that %%parties|party%% may create, maintain and use in a self-sovereign fashion - which means that each of them decides for itself what terms to use in what meaning, yet be able to communicate with other such %%parties|party%% in such a way that a correct understanding of what the other means, can more or less be guaranteed.
## Introduction
<!--Gently introduce the pattern, by referring to real-world situations and using colloquial terms, so that when someone has read the text, (s)he knows what it is about, and is ready to delve into the specifics of the pattern-->
TL;DR: .
A concept is an idea that is applied to all objects in a group. It is the way people see and understand something. The name used to identify a concept (the concept's label) is a "term". For example, the word "Dog" is the term to identify the concept of what a dog is. Everything that a person knows about a dog is the concept of the term dog.
Different terms can be used to identify the same concept. Car and Automobile are synonyms for the same concept. Different languages have different terms for the same concept. This is what makes translation possible. The terms may be different in each language, but the concept is the same. The concept of jumping is the same to a person from England and a person from Italy, but one person uses the term "Jump" to mean the concept and the other person uses "Salto".
## Notations
<!--This (optional) section specifies the notations that are used, or refers to such a specification.-->
## <!-- any number of other sections, as is fit for describing the pattern -->
<!--text as appropriate for such a section -->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
---
id: scope-essifLabTerminology
title: Scope eSSIF-Lab Terminology
---
## Governance
<!--This section identifies the organizational body (Jurisdiction) that governs the scope. Optionally, a reference to the governance framework/procedures may be made.-->
The [eSSIF-Lab project](https://essif-lab.eu/) governs the terminology within this scope, according to the procedures mentioned in the [eSSIF-Lab Framework](https://essif-lab.pages.grnet.gr/framework/docs/terminology/).
## Objectives/Issues
<!--State the purpose for having the scope in terms of objectives that are aimed for and/or issues that are to be addressed.-->
Contributors to and users of eSSIF-Lab come from various backgrounds. Their culture may not be Western. English may not be their native tongue. They may be experts in non-technological topics. Working with one another presumes a setting where participants have some level of shared understanding. Often, sharing one's understanding at a superficial level suffices. Other situations require that underlying concepts are shared in a more in-depth fashion. It's like cars: people buying, selling, or driving cars do not need in-depth shared knowledge about cars, whereas (maintenance or construction) engineers or liability lawyers need to share a deeper knowledge of how cars do (or do not) work.
We expect to see situations of "language confusion", i.e. in which people use words or phrases, the intension (not: intention) of which differs from the interpretation of some listeners/readers. Sometimes a casual glance at a dictionary or glossary is the solution. In other cases, deeper understanding matters, e.g. in when drafting specifications or contracts. Then we need more than a set of definitions.
The Concepts and Terminology part of eSSIF-Lab aims helps eSSIF-Lab community participants understand one another at whatever level of precision they need.
## Scope URI
<!--Optionally specify the URI by which this scope may be identified-->
## Inclusions
<!--This scope may include other scopes, which means that everything in that other scope is also considered part of this scope. In case of collisions, this scope MUST provide a means to resolve such conflicts without modifying anything in included scopes. For eSSIF-Lab, we include `essifLabTerminology`-->
## Notes
<!--Anything els that's worth mentioning.-->
## Tags
<!--Add hash tags here that allow us to group concepts in useful ways.-->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
---
id: ExistingScopeID-conceptproposal-NewTermID
title: "Concept proposal for: <NewTermID> (Scope: <Existing Scope>)"
scopeid: <ExistingScopeID>
term: <NewTerm>
hoverText: "<Text that pops up when the user hovers over a reference to this concept>"
---
<!--A concept tries to capture the idea behind a classification of entities, allowing us to reason about everything in the class as if it were one thing. This file specifies the idea(s) that, within the scope of `<ExistingScopeID>` will be referred to using <New Term>.
Please fill in the placeholders in this file as follows:
- `<ExistingScopeID>`: identifier of the scope in which the term is defined;
- `<Existing Scope>`: human readable text that identifies the scope in which this item is defined;
- `<NewTerm>`: term that will identify the concept within <ExisingScopeID>;
- `<ExistingTerm>`: term by which the concept is concept is known in that scope
-->
## One-line Summary
A single sentence that describe the concept to a layperson with reasonable accuracy. This line may be used to explain `Concept` in a glossary, or as a popover text when it is referred to in other documentation.
For example: "A warm-blooded animal, often having fur or hair, that produces milk to feed its young."
## Short Description
in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.
For example, the concept of a "mammal" in biology might be described as: "A warm-blooded animal, often having fur or hair, that produces milk to feed its young. Examples include rats, whales, and bats." A diagram could be included, if appropriate. The goal here is not perfect clarity; that's the focus of the 'Criteria' section.
## Purpose
Describe why the concept is needed. What purposes does it serve? What can you do with it that you cannot do (as well) without it? What objectives does it help realize? Why is this concept relevant within its scope of definition?
## Criteria
How is this concept different from related ideas? What are essential characteristics that must be true? This is where you specify the [intensional definition](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions) of the concept, i.e. the necessary and sufficient conditions for when the term should be used. This makes that the concept becomes crystal clear. In the case of nouns, this is equivalent to specifying the properties that an object needs to have in order to be counted as a referent of the term.
a vertibrate that has mammary glands, a neocortex in the brain and 3 middle ear bones.
## Examples
Provide a few sentences in which you give examples that obviously qualify as instances of NewTerm, and that do NOT obviously qualify. Also, provide examples that are not (so) obvious, but help users to better understand its intension.
Primates (humans, monkeys), rodents (mice, rats), bats, and others qualify. Birds and reptiles do not (they lack mammary glands). [Platypus](https://en.wikipedia.org/wiki/Platypus)[^1] is also a mammal, even though it lays eggs.
## Related Concepts
Link to any concepts that are similar but distinct, with a note about the relationship. For example:
* offspring (of a mammal) is the set of mammals that are born from that mammal.
* mate (of a mammal) is any mammal of the same species with which the mammal has created ofspring.
## Domains
In which general knowledge ecosystems or mental model families does this concept play a role? For example:
* Biology
## Tags
Add hash tags here that allow us to group concepts in useful ways.
## Use-cases
<!--This (optional) section specifies an (optional) introductory paragraph, and a level-3 (i.e. `###`) subsection for every use case it describes. Every such use-case SHOULD
- describe the situation/context of the use-case;
- show how to apply `NewTerm` to/in that situation;
- shows the relevance of having `NewTerm` for the use-case as opposed to not having it. -->
## Notes
<!--This (optional) section is the place to put anything for which there is no other good place to put it. -->
<!--
---
## Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment