Skip to content

Authoring terminology-related files (i.e. for Terms, Concepts, Patterns, Scopes and Glossaries)

In this issue, which unifies (and hence closes) issues #7 (closed), #8 (closed), #9 (closed), we specify the requirements that authors of terminology-related files must adhere to. This top message contains these requirements. Any updates to the requirements will lead to this top message to be edited/updated, so that it always contains the latest state of affairs. Subsequent messages document the discussions.

We currently have the following terminology related items:

  • a scope is something within which concepts can be associated with terms for a specific purpose, thereby creating a vocabulary that can be used to meaningfully express ideas, arguments, etc. so as to realize that purpose. For the sake of this issue, a scope serves the same purposes as a namespace.
  • a pattern captures a set of concepts, 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. A pattern must be defined within a scope.
  • a concept tries to capture the idea behind a classification of entities, allowing one to reason about everything in the class as if it were one thing. It MUST be defined within a scope, and in conjunction with a term that is used to refer to instances of the concept in that scope.
  • a term is a word or phrase that is used in at least one scope to refer to some concept; it is a 'link' between a scope and a concept, allowing each scope to define its own terms, yet build on the concepts developed by others. Obviously, terms too MUST be defined in a scope, as a reference to a concept (possibly, but not necessarily, from another scope).
  • 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). A glossary MUST be defined in a scope.

We have a template file for every such item

  • For TEv1,
    • templates can be found in docs/terminology-engine-v1-templates
    • you should only use the templates for a concept, term, or pattern (for the other stuff TVv1 has no generators).
    • copy the template to the docs/terms directory, rename it in an appropriate fashion, then edit the header (instructions are included in the template), and add the content (preferably according to the structure provided in the template).
  • For TEv2
    • templates can currently be found in doc-sources/terminology/templates.
    • we will describe their use when TEv2 gets underway.
Edited by Rieks Joosten