Commit 7aba486f authored by Rieks Joosten's avatar Rieks Joosten

terminology updates (still WIP)

parent 0a5dea05
Pipeline #15703 passed with stage
in 1 minute and 33 seconds
---
id: TBD
title: "TO BE DONE"
---
:::info **UNDER CONSTRUCTION**
This page is a placeholder for pages that need to be authored.
:::
This diff is collapsed.
---
id: notations-and-conventions
title: Notations and Conventions Used in this Documentation
sidebar_label: Notations
title: Notations and Conventions
---
Here, we provide an overview of the notations and conventions being used within eSSIF-Lab.
This document provides an overview of the notations and conventions being used within eSSIF-Lab.
## RFC 2119
### RFC 2119
We shall use keywords such as “shall”, “should”, “may” etc. as defined by [RFC 2119](https://www.ietf.org/rfc/rfc2119.txt).
## Capitalization of words in mid-sentence
Also, we capitalize words in mid-sentence whenever it is used in the meaning as provided by a corresponding Definition. This allows us to also use the more colloquial meanings of words (by not capitalizing them). We appreciate any feedback regarding our (im)proper use of this kind of capitalization of words.
### Capitalization of words in mid-sentence
A word in mid-sentence that is capitalized is a %%term|term%% that has a %%definition|definition%% in the %%Corpus of Terminology|corpus%%. This allows readers to distinguish between the more colloquial meanings of words (by not capitalizing them) and those that are actually defined. We appreciate any feedback regarding our (im)proper use of this kind of capitalization of words.
We are working towards deprecating this convention, as we now have better ways to refer to %%definitions|definition%%.
:::note
We are working towards deprecating this convention, as we now have better ways of referring to words that are defined in the eSSIF-Lab Corpus..
## Pattern diagram notations
### Pattern diagram notations
%%Pattern|pattern%% diagrams will be visualized in this document using a UML-like notation, as follows:
......
---
id: terminology-contributions
title: "How To Contribute to the eSSIF-Lab Terminology Effort"
sidebar_label: Contributing to the Terminology Effort
scopeid: essifLab
---
import useBaseUrl from '@docusaurus/useBaseUrl';
:::info **UNDER CONSTRUCTION**
TNO to provide further contents
:::
......@@ -15,42 +15,42 @@ Please fill in the placeholders in this file as follows:
- `<New Term>`: human readable text that identifies this term within `<Existing Scope>`;
-->
## Short Description
### Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
## Purpose
### 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
### 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 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.-->
## Examples
### Examples
<!--Provide a few sentences in which you give examples that obviously qualify as instances of `<New 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
### Related Concepts
<!--Link to any concepts that are similar but distinct, with a note about the relationship.-->
## Background:
### Background
<!--Mention and link to the patterns in which this concept plays a (significant) role (possibly explaining the reason/purpose if appropriate), e.g.: The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.-->
## Domains
### Domains
<!--In which general knowledge ecosystems or mental model families does this concept play a role?-->
## Tags
### Tags
<!--Add hash tags here that allow us to group concepts in useful ways.-->
## Use-cases
### 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 `<New Term>` to/in that situation;
- shows the relevance of having `<New Term>` for the use-case as opposed to not having it.-->
## Notes
### Notes
<!--This (optional) section is the place to put anything for which there is no other good place to put it.-->
<!--
---
## Footnotes
### Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
......
......@@ -11,8 +11,8 @@ hoverText: "DictionaryID: popuptext for 'dictionaryID' (tbd)."
This template lets you define the specifications according to which a specific dictionary is generated.
-->
## Purpose
### Purpose
<!--State the purpose(s) that this dictionary aims to fulfill, in such a way that readers can easily determine whether or not it is useful for them to use it. This text appears as the introduction of the (generated) dictionary.-->
## Scopes
### Scopes
<!--This section specifies the various scopes from which terms are included in the dictionary-->
......@@ -14,10 +14,10 @@ Please fill in the placeholders in this file as follows:
- `<new-glossaryID>`: identifier by which the glossary can be identified within <existing-scopeID>;
-->
## Purpose
### 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.-->
## Sources
### Sources
<!--This section specifies the sources from which the glossary entries (and their descriptions) are to be collected. All terms from all sources are included in the glossary. If that is too much, then you should revert to stating individual terms, patterns or concepts (see below).-->
### Terms
......@@ -34,7 +34,7 @@ Please fill in the placeholders in this file as follows:
<!--
---
## Footnotes
### Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
......
......@@ -15,13 +15,13 @@ Please fill in the placeholders in this file as follows:
- `<New Pattern>`: human readable text that identifies this pattern within <Existing Scope>;
-->
## Purpose
### Purpose
<!-- Concisely describe what can you do with the pattern that is (at least) harder if you didn't have it. -->
## Introduction
### 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. -->
## Notations
### 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 -->
......@@ -29,10 +29,10 @@ Please fill in the placeholders in this file as follows:
<!--
---
## Footnotes
### Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
[^1]: the text for footnote [^1] goes here.
-->
-->
\ No newline at end of file
......@@ -14,27 +14,27 @@ Please fill in the placeholders in this file as follows:
- `<New Scope>`: human readable text that identifies the new subscope;
-->
## Governance
### Governance
<!--This section identifies the organizational body (Jurisdiction) that governs the scope. Optionally, a reference to the governance framework/procedures may be made.-->
## Objectives/Issues
### 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.-->
## Scope URI
### Scope URI
<!--Optionally specify the URI by which this scope may be identified-->
## Inclusions
### 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
### Notes
<!--Anything els that's worth mentioning.-->
## Tags
### Tags
<!--Add hash tags here that allow us to group concepts in useful ways.-->
<!--
---
## Footnotes
### Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
......
......@@ -18,15 +18,15 @@ Please fill in the placeholders in this file as follows:
- `<ExistingtermID>`: machine readable identifier that identifies a concept within <ExistingConceptScopeID>
-->
## Purpose
### Purpose
<!--State the purpose(s) for which it is necessary (or at least: desirable) to define <New Term>.-->
## Notes
### Notes
<!--Usually, the meaning of a term will not be _exactly_ the same as that of the concept to which it refers. Often, there are slight differences in meaning, or the term may emphasize specific characteristics of the concept, so as to accommodate specific needs of the scope in which it is defined. Please describe such deviations/emphasized characteristics in this section, and which needs that helps accommodate.-->
<!--
---
## Footnotes
### Footnotes
[//]: # This (optional) section contains any footnotes that may have been specified in the text above.
......
This diff is collapsed.
# 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
......@@ -8,22 +8,22 @@ stage: draft
hoverText: "Action: something that is actually done/executed by a single actor (as a single operation) for some party within a specific context."
---
## Short Description
### Short Description
An **Action** is something that is actually done/executed by a %%actor|actor%% in some context (i.e. in a specific place, at a specific time). During the time interval in which the action is executed, the actor may still execute other actions in other execution-contexts (multi-tasking). An action is executed for, or on behalf of, a specific %%party|party%%, which means that the primary guidance for executing the action, e.g. how to execute it, boundary conditions within which the execution must take place, etc., comes from the %%knowledge|knowledge%% of that party. The actor is assumed to have appropriate access to the knowledge of that party. In order to properly execute the action, the executing actor may also use additional knowledge(s) to which it has access.
## Purpose
### Purpose
The ability to distinguish between (non)actions allows one to determine which (kinds of) %%actors|actor%% are capable of executing actions (e.g. by establishing that they have the competences required by the party), and as a consequence may be permitted and/or required to execute them. Also, this ability enables parties to determine the execution-policy, i.e. the set of rules and other guidance that actors should obey or comply with when exeucting an action on its behalf.
## Criterion:
### Criterion
An **Action** is something that is done by an actor, can be considered a single operation, and is performed in a specific context, for or on behalf of a specific party, i.e. in accordance with the policy rules that this party has established for such actions.
## Examples:
### Examples
- filling in a form and submitting it.
- cleaning a car.
## Related Concepts
### Related Concepts
<!--Link to any concepts that are similar but distinct, with a note about the relationship.-->
- OED defines Action as the fact or process of doing something, typically to achieve an aim ([OED](https://www.lexico.com/definition/action)), which is too generic for our purposes.
## Background:
### Background
The %%party-action pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
\ No newline at end of file
......@@ -8,21 +8,21 @@ stage: draft
hoverText: "Actor: Entity that can act (do things), e.g. people, machines, but not organizations."
---
## Short Description
### Short Description
An **Actor** is someone or something that can actually do things, such as people or machines. Actors will generally do things, i.e. execute %%actions|action%% in different ways, depending on the context, or the %%party|party%% for whom they do this.
## Purpose
### Purpose
The ability to distinguish between (non)actors allows one to determine which (kinds of) actors are capable of executing which (kinds of) %%actions|action%%, specifically since %%organizations|organization%% do not qualify as an actor (they need actors to get things done).
## Criterion:
### Criterion
Entity that is capable of actually executing %%actions|action%% (acting, doing things).
## Examples:
### Examples
- People (human beings) obviously qualify, as do robots and other machines.
- Stones, pictures, ideas, etc. do not qualify.
- Software applications qualify, provided they are actually running on hardware. An app that is just sitting e.g. on a mobile phone but isn't executed does not qualify.
- Enterprises, governments, and other %%organizations|organization%% do not qualify.
## Background:
### Background
The %%party-action pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
......@@ -5,20 +5,20 @@ scopeid: essifLab
type: concept
typeid: agent
stage: draft
hoverText: "Agent: An actor that is (at that point in time) executing an action for, or on behalf of a Party."
hoverText: "Agent: An actor that is (at that point in time) executing an action for, or on behalf of a Party (the Principal of that actor)."
---
## Short Description
%%Actors|actor%% execute %%actions|action%% for, or on behalf of some %%party|party%%, because parties are not considered to be capable of acting.[^1] Agents must act in accordance with the party for which they execute such actions, which means that for every kind of action, such parties must provide the proper guidance for their agents, e.g. in terms of policies (rules), working instructions, programs etc. We use the term %%digital agent|digital-agent%%
### Short Description
%%Actors|actor%% execute %%actions|action%% for, or on behalf of some %%party|party%% (the %%principal|principal%% of that agent), because parties are not considered to be capable of acting.[^1] Agents must act in accordance with their %%principal|principal%%, which means that for every kind of action, the principal must provide the proper guidance for their agents, e.g. in terms of policies (rules), working instructions, programs etc. We use the term %%digital agent|digital-agent%% to refer to agents that operate in a digital domain.
## Purpose
### Purpose
The ability to distinguish between (non)agents is relevant in many situations, including:
- electronic communication: the agent
## Criterion:
a property that is attributed to an %%Actor|actor%% whenever it is executing an action for, or on behalf of some %%party|party%%.
### Criterion
a property that is attributed to an %%Actor|actor%% whenever it is executing an action for, or on behalf of some %%party|party%% (its %%principal|principal%%).
## Examples:
### Examples
- A person that is 'doing its own things' acts as an Agent for himself.
- A person that does things for his employer acts as an Agent for that employer.
......@@ -28,5 +28,5 @@ a property that is attributed to an %%Actor|actor%% whenever it is executing an
- A (running) webserver that accepts product orders for a retailer acts as a (digital) Agent for that retailer.
- A wallet app that runs on a phone and that is exclusively used by a single person acts as a (digital) Agent for that person.
## Background:
### Background
The %%party-action pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.
......@@ -8,14 +8,14 @@ stage: draft
hoverText: "Concept-file: a file that defines/specifies a concept."
---
## Short Description
### Short Description
A **concept-file** is a file that contains documentation about a specific %%concept|concept%%. To faciliate authors, a self-explanatory [template file](/terminology-engine-v1-templates/concept-file.md) is available.
## Purpose
### Purpose
The ability for people to determine whether or not they are talking about the same 'thing' (idea, concept), is prerequisite for knowing that they (correctly) understand one another - which doesn't imply they agree with each other. Concept files provide the documentation of such %%things|concept%% that contribute to this ability.
## Criterion:
### Criterion
a file that defines/specifies a concept.
## Examples:
### Examples
the file that contains this text is an example of a concept-file.
......@@ -8,33 +8,33 @@ stage: draft
hoverText: "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."
---
## Short Description
### Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
A Concept tries to capture the idea behind a classification of entities[^1], allowing us to reason about everything in the class as if it were one thing. For example, the ideas ([mental representations](https://en.wikipedia.org/wiki/Mental_representation)) you have when processing the sentences "I can drink beer from a beer glass' and 'I can drink beer from a coffee mug' shows that the concepts that are behind 'beer glass' and 'coffee mug' differ. Note that in order to communicate about this idea, we also need a word or phrase (i.e.: a termat we can use to refer to (instances of) this idea.
## Purpose
### 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?-->
Working together is easier when you and your peers share the same ideas. We need a way to test and ensure, that you and your peers _actually_ have the same understanding, for the purpose of making cooperation easier. Doing so is expected to not only reduce the number of terminological discussions, but also improve the efficiency and effectiveness of the remaining discussions.
## Criteria
### 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.-->
A (description/specification of a) Concept MUST be [intensionally defined](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions), i.e. associated with a criterion that can be used to determine whether or not someone or something qualifies as (an instance of) that Concept, and that has the property that it has been shown that the vast majority of contributors and other users apply it in the same manner in different situations (i.e. they arrive at the same conclusion as to whether or not someone or something qualifies under that criterion in any given situation).
## Examples
### Examples
<!--Provide a few sentences in which you give examples that obviously qualify as instances of `Concept`, and that do NOT obviously qualify. Also, provide examples that are not (so) obvious, but help users to better understand its intension.-->
## Related Concepts
### Related Concepts
<!--Link to any %%concepts|concept%% that are similar but distinct, with a note about the relationship.-->
* Term is a label that is used in some context to refer to a %%Concept|concept%%[^2], the set of entities that satisfy the concept's criteria, or an arbitrary element of that set. Different contexts may use different terms to refer to a single concept. In a single context, a single term should be used to refer to an individual concept.
* %%Term|term%% is a label that is used in some context to refer to a %%Concept|concept%%[^2], the set of entities that satisfy the concept's criteria, or an arbitrary element of that set. Different contexts may use different terms to refer to a single concept. In a single context, a single term should be used to refer to an individual concept.
* Concept ... ("Scope") is related in several ways. First, there is (precisely, or at most one) Scope that governs the definition/specification of the Concept. Second, there may be (any number of) Scopes that use the Concept, i.e. within which Terms are defined that refer to the Concept
* %%Scope|scope%% is related in several ways. First, there is (precisely, or at most one) Scope that governs the definition/specification of the Concept. Second, there may be (any number of) Scopes that use the Concept, i.e. within which Terms are defined that refer to the Concept
* Concept ... ("Conceptual Model") is a collection of concepts, relations between such concepts, and constraint rules that (elements of) such concepts and relations must satisfy. Such [models](https://en.wikipedia.org/wiki/Conceptual_model) are used to help people know, understand, or simulate a subject the model represents.
* %%Mental(or Conceptual) Model|pattern%% is a collection of concepts, relations between such concepts, and constraint rules that (elements of) such concepts and relations must satisfy. Such [models](https://en.wikipedia.org/wiki/Conceptual_model) are used to help people know, understand, or simulate a subject the model represents.
## Background:
### Background
The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.
## Domains
### Domains
<!--In which general knowledge ecosystems or mental model families does this concepty a role?-->
* essifLab
* ToIP
......@@ -43,17 +43,17 @@ The %%terminology pattern|pattern-terminology%% provides an overview of how this
* NIST
* ...
## Tags
### Tags
<!--Add hash tags here that allow us to group concepts in useful ways.-->
* Terminology
## Use-cases
### 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 ``Concept`` to/in that situation;
- shows the relevance of having ``Concept`` for the use-case as opposed to not having it.-->
## Notes
### 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 between concepts and the (multitude of) terms](https://simple.wikipedia.org/wiki/Concept) (names, labels) that we need to be able to talk and reason (argue) about them. Please consider that
......@@ -62,7 +62,7 @@ There is an important [distinction between concepts and the (multitude of) terms
* 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
### 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).
......
---
id: concepts
title: "Concept: Concept (Scope: essifLabTerminology)"
scopeid: essifLabTerminology
termid: concept
hoverText: "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."
---
## Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
A Concept tries to capture the idea behind a classification of entities[^1], allowing us to reason about everything in the class as if it were one thing. For example, the ideas ([mental representations](https://en.wikipedia.org/wiki/Mental_representation)) you have when processing the sentences "I can drink beer from a beer glass' and 'I can drink beer from a coffee mug' shows that the concepts that are behind 'beer glass' and 'coffee mug' differ. Note that in order to communicate about this idea, we also need a word or phrase (i.e.: a termat we can use to refer to (instances of) this idea.
## 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?-->
Working together is easier when you and your peers share the same ideas. We need a way to test and ensure, that you and your peers _actually_ have the same understanding, for the purpose of making cooperation easier. Doing so is expected to not only reduce the number of terminological discussions, but also improve the efficiency and effectiveness of the remaining discussions.
## 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.-->
A (description/specification of a) Concept MUST be [intensionally defined](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions), i.e. associated with a criterion that can be used to determine whether or not someone or something qualifies as (an instance of) that Concept, and that has the property that it has been shown that the vast majority of contributors and other users apply it in the same manner in different situations (i.e. they arrive at the same conclusion as to whether or not someone or something qualifies under that criterion in any given situation).
## Examples
<!--Provide a few sentences in which you give examples that obviously qualify as instances of `Concept`, 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 <Term popup="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." reference="concept">concepts</Term> that are similar but distinct, with a note about the relationship.-->
* Term is a label that is used in some context to refer to a %%Concept%%[^2], the set of entities that satisfy the concept's criteria, or an arbitrary element of that set. Different contexts may use different terms to refer to a single concept. In a single context, a single term should be used to refer to an individual concept.
* Concept ... ("Scope") is related in several ways. First, there is (precisely, or at most one) Scope that governs the definition/specification of the Concept. Second, there may be (any number of) Scopes that use the Concept, i.e. within which Terms are defined that refer to the Concept
* Concept ... ("Conceptual Model") is a collection of concepts, relations between such concepts, and constraint rules that (elements of) such concepts and relations must satisfy. Such [models](https://en.wikipedia.org/wiki/Conceptual_model) are used to help people know, understand, or simulate a subject the model represents.
## Domains
<!--In which general knowledge ecosystems or mental model families does this concepty a role?-->
* essifLab
* 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 ``Concept`` to/in that situation;
- shows the relevance of having ``Concept`` 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: corpus
title: "Corpus of Terminology"
scopeid: essifLabTerminology
type: concept
typeid: corpus
stage: draft
hoverText: "Corpus (of Terminology): the documentation that describes the knowledge around a set of terms and concepts."
---
......@@ -8,15 +8,15 @@ stage: draft
hoverText: "Definition: A Definition is a text that helps parties truely understand the meaning of a term."
---
## Short Description
### Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
A **Definition** is a text that helps parties truly understand the meaning of a %%term|term%% as it is used in a communication. Because [terms are scoped](terminology), this 'truly understanding' of one another isn't trivial. Therefore, we insist that the explanatory text be a criterion that parties are expected to use in the same way in some %%scope(s)|scope%%, allowing them to establish whether or not they make the same determination as to whether or not something qualifies to be refered to by that term in a way that is independent of whether or not the (alledged) meaning is relevant for the purposes they pursue within that scope.
## Purpose
### 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?-->
Working together is easier when you and your peers share the same ideas. We need a way to test and ensure, that you and your peers _actually_ have the same understanding, for the purpose of making cooperation easier. Doing so is expected to not only reduce the number of terminological discussions, but also improve the efficiency and effectiveness of the remaining discussions.
## Criteria
### 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.-->
Entity that comprises at a minimum:
- a non-empty set of %%scopes|scope%% in each of which specific objectives are being pursued;
......@@ -24,12 +24,12 @@ Entity that comprises at a minimum:
- a set of arguments and/or use-cases (that SHOULD not be empty), and that show the relevance of making this distinction within the scope (and for its objectives);
- a %%name|term%% that is created and used within the scope that created the definition, for the purpose of referring to (instances of) the class, or using it as a placeholder for its instances.
## Examples
### Examples
<!--Provide a few sentences in which you give examples that obviously qualify as instances of `Concept`, and that do NOT obviously qualify. Also, provide examples that are not (so) obvious, but help users to better understand its intension.-->
- The definition of the term %%definition|definition%% (a) is defined in, and hence valid in the scope `eSSIFLab`, (b) specifies a criterion (see the `Criteria` section above), and (c) is relevant (see the `Purpose` section above), and (d) has a name (i.e. `definition`) associated with it. Since it satisfies the criteria of `definition`, it can be referred to as 'the definition of `definition`'.
- The %%concepts|concept%% defined within the scope eSSIFLab have definitions associated with them, where the criteria, relevance and terms are defined in the %%concept-file|concept-file%% of that concept.
## Related Concepts
### Related Concepts
<!--Link to any %%concepts|concept%% that are similar but distinct, with a note about the relationship.-->
* %%Term|term%% is a label that is used in some context to refer to a %%Concept|concept%%, the set of entities that satisfy the concept's criteria, or an arbitrary element of that set. Different contexts may use different terms to refer to a single concept. In a single context, a single term should be used to refer to an individual concept.
......@@ -37,18 +37,25 @@ Entity that comprises at a minimum:
* %%Mental(or Conceptual) Model|pattern%% is a collection of concepts, relations between such concepts, and constraint rules that (elements of) such concepts and relations must satisfy. Such [models](https://en.wikipedia.org/wiki/Conceptual_model) are used to help people know, understand, or simulate a subject the model represents.
## Background:
### Background
The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.
## Use-cases
### 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 ``Concept`` to/in that situation;
- shows the relevance of having ``Concept`` for the use-case as opposed to not having it.-->
## Notes
### Notes
<!--This (optional) section is the place to put anything for which there is no other good place to put it.-->
For the purposes of this document, the scope of every Definition is this Document (with its objectives that have been specified above).**
Note that this definition satisfies itself. Also note that a definition may be used in multiple scopes, where a scope that wants to use the definition that has been defined in another scope, may replace that name with one of its own choosing. This way the meaning expressed by the definition remains preserved.
You may want to create definitions that are both acceptable for business people (for whom it usually suffices that they get the gist of it) as for engineers (that need much more precision, up to the point where they can use it for formal reasoning). You face the challenge of conveying your intangible ideas or %%concepts|concept%% with tangible words or phrases. You can do this by using [intensional definitions](https://en.wikipedia.org/wiki/Extensional_and_intensional_definitions), i.e. by defining criteria that specify *the necessary and sufficient conditions* for when the term you define should (not) be used. When defining such criteria, make sure they have the following properties:
- you are convinced that the vast majority of people in your audience will *make the same judgements as you do when applying these criteria* in a situation that you and your audience consider relevant; and
- the *ability to make this distinction is relevant* for one or more purposes of your intended audience.
Note that the actual word or phrase you choose as the %%term|term%% name for a concept is much less important than the criteria you define. If in a particular %%context|scope%% another name would be more suitable, you can define another %%term|term%% for that other context (scope) that still refers to the concept you created the definition for.
The %%Terminology Corpus|corpus%% provides templates that help you do that, e.g. for %%defining concepts|concept-file%% and for %%defining terms|term-file%%.
......@@ -8,11 +8,11 @@ stage: draft
hoverText: "Dictionary-file: a file that specifies the contents of a dictionary."
---
## Short Description
### Short Description
A **dictionary-file** is a file that contains the specification of what does (not) go into a specific %%dictionary|dictionary%%. To faciliate authors, a self-explanatory [template file](/terminology-engine-v1-templates/dictionary-file.md) is available.
## Purpose
### Purpose
%%Dictionaries|dictionary%% help people to figure out the meaning of terms, specifically if the context of the text they are interpreting isn't very clear, or the meaning of the used terms is left to the imagination of the reader.
## Criterion:
### Criterion
a file that defines/specifies a %%dictionary|dictionary%.
......@@ -8,37 +8,37 @@ stage: draft
hoverText: "Dictionary: 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)."
---
## Short Description
### Short Description
<!--REQUIRED--in 1-3 sentences that describe the concept to a layperson with reasonable accuracy.-->
A Dictionary is an alphabetically sorted list of terms and explanations. Each term may have multiple such explanations, which come from different %%scopes/contexts|scope%%.
## Purpose
### 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 dictionary helps people to get introduced in the domain for which the dictionary is created. Usually, this is a larger domain e.g. of some language, or about computer security.
## Criteria
### 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 possibly multiple, short explanations, that exists for the purpose of helping people to find out what a word may mean in various %%scopes/contexts|scope%%.