This document states the requirements for files in this directory, such that they can properly processed into useful and useable Docusaurus documentation.
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:
-`<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:
-`1-scope`
-`2-pattern`
-`3-concept`
-`4-term`
-`5-glossary`
-<instanceid> MUST be a lowercase identifier that only uses charancters `a`-`z` and `-`.
-`<instanceid>` MUST be a lowercase identifier that only uses characters `a`-`z` and `-`.
## Templates
The `terminology/templates` directory contains templates for each of the <type>s. A template file has comments that hold, amongst others, requirements for the contents of instances of that template.
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
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
-`<sometext>` is a text that will be displayed as if it were a term
<!--A %%pattern%% capture a set of %%concepts:concept%%, relations between them, and rules or constraints that (instances) thereof comply with. As such, it is a concise and possibly formal description of a coherent set of ideas, a mental model if you will, that can be used to facilitate one's thinking about/with these concepts.
This file documents a pattern called `<NewPattern>` within the scope of `<ExistingScope>`.
...
...
@@ -23,7 +21,6 @@ This pattern captures the foundational concepts and relations that we need for t
<!--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: This pattern models that %%Parties:Party%% (humans, organizations) perform %%Actions:Action%% for the purpose of realizing their %%Objectives:Objective%%. %%Parties:Party%% are not considered to actually execute such %%Actions:Action%%; they have (human and non-human) %%Actors:Actor%% that work for them, execute such %%Actions:Action%%, using the %%Party%%’s %%Knowledge%% as the (authoritative) guidance for executing the %%Actions:Action%% (as well as any other relevant %%Knowledge%% they can access).
<Image src=pattern-Party-action.png />
The essential characteristic of %%Parties:Party%% is their 1-1 link with %%Knowledge%%, which they continually update and use e.g. for reasoning, decision making, and determining e.g. what to do, when, and with whom. %%Knowledge%% not only includes (observable) facts, but also opinions, e.g. regarding the %%Entities:Entity%% it knows to exist, relations between them, and rules (constraints, [logic](https://en.wikipedia.org/wiki/Logic)[^1]) that can be used to classify and reasoning about them, and for making decisions.
<!--A %%glossary%% is a list of %%terms:term%% with (short) explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s).-->
<!--A %%pattern%% capture a set of %%concepts:concept%%, relations between them, and rules or constraints that (instances) thereof comply with. As such, it is a concise and possibly formal description of a coherent set of ideas, a mental model if you will, that can be used to facilitate one's thinking about/with these concepts.
This file documents a pattern called `<NewPattern>` within the scope of `<ExistingScope>`.
<!--A %%concept%% tries to capture the idea behind a classification of %%entities:entity%%, 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 `<ExistingScope>` will be referred to using the %%term%% `<NewConcept>`.
Before completing this template, please change every instance of
<!--A %%glossary%% is a list of %%terms:term%% with (short) explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s).-->
<!--A %%scope%% is something within which %%concepts:concept%% can be associated with %%terms:term%%, thereby creating a vocabulary that can be used to meaningfully express ideas, arguments, etc.-->
<!--A %%pattern%% captures a set of %%concepts:concept%%, relations between them, and rules or constraints that (instances) thereof comply with. As such, it is a concise and possibly formal description of a coherent set of ideas, a mental model if you will, that can be used to facilitate one's thinking about/with these concepts.
This file documents a pattern called `<NewPattern>` within the scope of `<ExistingScope>`.
<!--A %%concept%% tries to capture the idea behind a classification of %%entities:entity%%, 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 `<ExistingScope>` will be referred to using the %%term%% `<NewConcept>`.
Before completing this template, please change every instance of
<!--A Term is a word or phrase that is used in at least one scope (context and/or for specific purposes) to refer to `<ExistingConcept>`, which is an existing %%concept%%.
<!--A %%glossary%% is a list of %%terms:term%% with (short) explanations, usually aimed to help people understand texts around a certain (set of) topic(s) in some context(s).-->
title: Concept proposal for <NewConcept> (Scope <ExistingScope>)
---
<!--Replace 'NewConcept' with the name for the concept you want to define. Then, provide contents for the sections as you wish. You MUST provide contents for the sections 'Scope of definition', 'Short Description' and 'Criteria'-->
