Commit a916eb1a authored by Rieks Joosten's avatar Rieks Joosten Committed by fmerg
Browse files

cleaning up some more

parent 6bf413a5
Pipeline #15648 failed with stage
in 2 minutes and 18 seconds
......@@ -4,7 +4,6 @@ title: Terminology & Glossary plugin docs
import useBaseUrl from '@docusaurus/useBaseUrl';
### How it works
This plugin parses docs in two ways:
id: terminology
title: "eSSIF-Lab: Concepts and Terminology"
title: "eSSIF-Lab Concepts and Terminology"
sidebar_label: Terminology
scopeid: essifLab
......@@ -9,11 +9,9 @@ scopeid: essifLab
*This (initial version of the) terminology chapter is currently under construction. If you feel like making a contribution, please contact [the editor](*
The purpose of the eSSIF-Lab Terminology is to provide mental models that all of its stakeholders interpret in sufficiently the same way, so as to be able to talk, think and discuss about what it is we try to achieve and ways to achieve this.
The eSSIF-Lab Terminology and Concepts effort is directed at providing tools, terminologies and (mental/conceptual) models, the purpose of which is to enable/facilitate its stakeholders in understanding one another as they communicate about topics that concern eSSIF-Lab (specifically: its arechitecture and components), and also to write document(ation)s in such a way that the other stakeholders have less trouble with understanding.
The initial version of this terminology is still under construction.
## Introduction
## Motivation
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.
......@@ -21,19 +19,19 @@ We expect to see situations of "language confusion", i.e. in which people use wo
The Concepts and Terminology part of eSSIF-Lab aims helps eSSIF-Lab community participants understand one another at whatever level of precision they need.
## Glossaries
The traditional tool for fostering common understanding is using glossaries, i.e. alphabetical lists of words relating to a specific subject, text, or dialect, with explanations; a brief dictionary ([OED]( Examples include the [Sovrin Glossary]( and the [NIST Glossary]( Other initiatives attempt to provide more background, e.g. the [terminology for talking about privacy by data minimization]( by Pfitzmann and Hansen (2010), or the [EBSI Terminology (login required)](
The eSSIF-Lab project will also develop a [Glossary](./essifLab-glossary).
## Terminological Artifacts
However, since the use of such glossaries is limited to short explanations, we will also provide (a) mental model(s) that provide a more in-depth explanation of the concepts that underly the words listed in the [eSSIF-Lab Glossary](./essifLab-glossary).
the eSSIF-Lab Concepts and Terminology effort aims to produce artifacts that help stakeholders for the purposes mentioned above. Currently, this comprises:
## Mental Models
- A set of (documented/defined) terms that can be easily referred to by document authors, according to [these instructions](./terminology-plugin-instructions).
- A [Glossary](./essifLab-glossary) that lists these terms, and is automagically updated as contributions to the eSSIF-Lab Terminology Corpus are being made.
- A set of %%mental models|mental model%% that provide backgrounds about how specific %%concepts|concept%% relate to one another.
We have the following mental (conceptual) models:
Depending on the needs of stakeholders, additional artifacts may be created/generated.
## Glossaries are useful, but do not solve all problems
The traditional tool for fostering common understanding is using glossaries, i.e. alphabetical lists of words relating to a specific subject, text, or dialect, with explanations; a brief dictionary ([OED]( Examples include the [Sovrin Glossary]( and the [NIST Glossary]( Other initiatives attempt to provide more background, e.g. the [terminology for talking about privacy by data minimization]( by Pfitzmann and Hansen (2010), or the [EBSI Terminology (login required)](
A Mental Model, or Conceptual Model, is a set of of concepts (i.e. entity classes), relations between such concepts (i.e. sets of pairs of members of classes that a relation connects), and rules/constraints expressed in terms of these relations and concepts.
......@@ -59,27 +57,3 @@ We attempt to create definitions that are both acceptable for business people ye
The actual texts we choose as the name for a concept is of secondary importance; if in a particular context other names are more suitable, you can rename them there without loss of meaning or consistency.
Together with these criteria, we provide a limited set of examples to help the reader to visualize the defined concepts, and to point out possibly unexpected consequences of the criteria. Also, we may motivate the need for having a concept by showing its relevance for the model.
Here are some examples:
### Entity
**someone or something that is known/thought of**.
Basically, anything you (or anyone else) can think of qualifies. That includes people, organizations, documents, data, ideas, etc. Things that you do not know that exist, but others do, also qualify.
Since there is nothing that you, or someone else, can come up with that does not satisfy the criterion, everything qualifies as an Entity. We need the term as a basis for creating intensional definitions.
**The following definitions will be moved to a separate eSSIF-Lab Terminology section**
### Definition
**Entity that comprises at a minimum**:
- **a non-empty set of scopes in each of which specific objectives are being pursued;**
- **a criterion that specifies the necessary and sufficient conditions for being an instance of a named class;**
- **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 that is created and used within the scope that created the definition, for the purpose of referring to the class, or using it as a placeholder for its instances.**
**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.
id: mental-model
title: "Mental Model"
scopeid: essifLab
type: term
typeid: mental-model
conceptref: essifLab:pattern
stage: draft
hoverText: "Mental Model: a casual and formal description (pattern) of a set of concepts, relations between them, and constraints, that provide a specific 'viewpoint', or 'way of thinking' about a certain topic."
see: %%pattern|pattern%%.
\ No newline at end of file
......@@ -5,7 +5,7 @@ scopeid: essifLab
type: pattern
typeid: terminology
stage: draft
hoverText: "The eSSIF-Lab Terminology Corupos pattern (further text remains to be written)."
hoverText: "The eSSIF-Lab Terminology Corpus pattern (further text remains to be written)."
import useBaseUrl from '@docusaurus/useBaseUrl';
......@@ -24,11 +24,18 @@ A (good) pattern can be used
<!--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]( 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 limited set of %%concepts|concept%% (preferably not exceeding 7+/-2)[^1], relations between such concepts, and constraints, such that together they form a coherent and consistent whole that can be used to explain one's thinking about a specific topic within a specific %%scope|scope%%.
## 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.-->
## Notes
## Related Concepts
<!--Link to any %%concepts|concept%% that are similar but distinct, with a note about the relationship.-->
The first purpose of a pattern is to help us think and reason about a certain topic or issue.
One signal that indicates the need of such a model is when we’re running circles in our thoughts, and we have this feeling of not understanding, of the topic being (too) complex. Often, we are thinking in terms of concepts that are not fit for the objectives we pursue.
So a pattern requires careful construction, that allows the choices for its elements to be validated against many use-cases. Such validation instills trust that our model elements (concepts, relations, rules) are well-chosen. It also provides us with the experience (usually after some time) that it has made our thinking easier, and we are better equipped to resolve issues.
The careful construction is comparable to a quest: it takes time, multiple versions, and careful reflection. And it needs continuous validation of its parts, by throwing use-cases at it and verifying that the model can describe such cases, and do some reasoning with them.
This careful construction must ensure that the mental model gets different properties. For starters, the pattern must be able to reason in (all) static situations, where things do not change, and the so-called ‘invariant’ rules/constraints must hold. Also, the model must be able to cope with time-dependencies and changes, for which other kinds of rules apply.
In the end, the pattern needs to be expressed in several, different ways, depending on whom we want to convey the ideas behind it to. Business people generally need simple models that allow them to (roughly) grasp its gist. Software architects need models with precise definitions that allow them to use its elements in (formal) reasonings. Software engineers (programmers) need all the details that allow them to create applications and databases that work according to the model’s intent. So the level of detail that an expression of the model provides, makes it useful or useless to different audiences.
## Background:
The %%terminology pattern|pattern-terminology%% provides an overview of how this concept fits in with related concepts.
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