From bcba9a6a55bd24492c83fe6eade896f3ac3dd49d Mon Sep 17 00:00:00 2001 From: Rieks Date: Fri, 11 Aug 2023 11:51:13 +0200 Subject: [PATCH] Website runs locally Signed-off-by: Rieks --- docs/{tev2 => }/README.md | 6 +- .../{tev2 => }/glossaries/mrg.tev2.terms.yaml | 88 +++--- docs/{tev2 => }/manuals/author.md | 0 docs/{tev2 => }/manuals/contributor.md | 0 docs/{tev2 => }/manuals/contributors-latex.md | 0 docs/{tev2 => }/manuals/contributors-repo.md | 0 docs/{tev2 => }/manuals/contributors-wiki.md | 0 docs/{tev2 => }/manuals/curator.md | 14 +- docs/{tev2 => }/manuals/tev2-installation.md | 6 +- .../miscellaneous/tool-development.md | 26 +- docs/{tev2 => }/mrgen.py | 0 docs/{tev2 => }/notations-and-conventions.md | 0 .../overview/00-tev2-common-understanding.md | 0 docs/{tev2 => }/overview/10-tev2-purpose.md | 4 +- .../overview/20-tev2-design-principles.md | 8 +- .../overview/30-tev2-architecture.md | 20 +- .../overview/40-tev2-terminology-curation.md | 16 +- docs/{tev2 => }/saf.yaml | 8 +- docs/{tev2 => }/showtexts-list.py | 0 docs/{tev2 => }/spec-files/00-ctext.md | 6 +- docs/{tev2 => }/spec-files/11-saf.md | 8 +- .../spec-files/20-profile-templates.md | 4 +- docs/{tev2 => }/spec-files/21-mrg.md | 12 +- docs/{tev2 => }/spec-files/22-hrg.md | 6 +- docs/{tev2 => }/spec-files/51-mrd.md | 0 docs/{tev2 => }/spec-files/52-hrd.md | 0 docs/{tev2 => }/spec-files/ingestion.profile | 4 +- .../spec-syntax/11-term-ref-syntax.md | 8 +- .../spec-syntax/21-form-phrase-syntax.md | 6 +- .../spec-syntax/31-hrg-termselcrit.md | 2 +- docs/{tev2 => }/spec-tools/11-ict.md | 4 +- docs/{tev2 => }/spec-tools/12-mrg-importer.md | 6 +- docs/{tev2 => }/spec-tools/13-trrt.md | 24 +- .../spec-tools/20-terminology-construction.md | 4 +- docs/{tev2 => }/spec-tools/21-mrgt.md | 32 +-- docs/{tev2 => }/spec-tools/22-hrgt-old.md | 2 +- docs/{tev2 => }/spec-tools/22-hrgt.md | 10 +- docs/{tev2 => }/spec-tools/31-mrdt.md | 4 +- docs/{tev2 => }/spec-tools/32-hrdt.md | 2 +- .../backgrounds/expressing-oneself.md | 17 -- docs/terminology-design/backlog.md | 24 -- docs/terminology-design/manuals/authoring.md | 73 ----- .../manuals/contributing.md | 20 -- docs/terminology-design/manuals/curating.md | 20 -- docs/terminology-design/methods.md | 73 ----- .../methods/1-1-discussions.md | 29 -- .../methods/criteria-elicitation.md | 64 ----- .../methods/real-life-example.md | 114 -------- .../methods/terminology-process.md | 88 ------ .../methods/why-design-thinking-works.txt | 133 --------- docs/terminology-design/mrgen.py | 257 ------------------ docs/terminology-design/overview.md | 71 ----- .../overview/00-common-understanding.md | 34 --- .../terminology-design/overview/10-purpose.md | 21 -- .../overview/20-design-principles.md | 18 -- docs/terminology-design/saf.yaml | 44 --- .../terminology-design/terms/.concept-file.md | 64 ----- docs/terminology-design/terms/author.md | 39 --- .../terms/common-understanding.md | 52 ---- .../terminology-design/terms/domain-expert.md | 42 --- .../terms/linguistic-unity.md | 42 --- docs/{terminology-design => }/terms/@.md | 0 docs/{tev2 => }/terms/_{termid}.mdx | 2 +- docs/{tev2 => }/terms/author.md | 2 +- docs/{tev2 => }/terms/body.md | 2 +- docs/{tev2 => }/terms/concept.md | 0 docs/{tev2 => }/terms/conceptualization.md | 2 +- docs/{tev2 => }/terms/converter.md | 2 +- docs/{tev2 => }/terms/corpus.md | 0 docs/{tev2 => }/terms/curate.md | 2 +- docs/{tev2 => }/terms/curated-text.md | 4 +- docs/{tev2 => }/terms/curatedir.md | 0 docs/{tev2 => }/terms/curator.md | 2 +- docs/{tev2 => }/terms/define.md | 2 +- docs/{tev2 => }/terms/definition.md | 0 docs/{tev2 => }/terms/dictionary.md | 0 docs/{tev2 => }/terms/formatted-text.md | 2 +- docs/{tev2 => }/terms/formphrase.md | 4 +- docs/{tev2 => }/terms/glossary.md | 0 docs/{tev2 => }/terms/glossarydir.md | 0 docs/{tev2 => }/terms/grouptag.md | 0 docs/{tev2 => }/terms/header.md | 2 +- docs/{tev2 => }/terms/hrd.md | 2 +- docs/{tev2 => }/terms/hrdt.md | 4 +- docs/{tev2 => }/terms/hrg-entry.md | 6 +- docs/{tev2 => }/terms/hrg.md | 2 +- docs/{tev2 => }/terms/hrgt.md | 8 +- docs/{tev2 => }/terms/ict.md | 8 +- docs/{tev2 => }/terms/identifier.md | 0 docs/{tev2 => }/terms/identify.md | 0 docs/{tev2 => }/terms/ingestion-process.md | 8 +- docs/{tev2 => }/terms/ingestion-profile.md | 2 +- docs/{tev2 => }/terms/interpreter.md | 4 +- docs/{tev2 => }/terms/knowledge-artifact.md | 0 docs/{tev2 => }/terms/mental-model.md | 0 docs/{tev2 => }/terms/moustache-variable.md | 2 +- docs/{tev2 => }/terms/mrd.md | 2 +- docs/{tev2 => }/terms/mrdt.md | 4 +- docs/{tev2 => }/terms/mrg-entry.md | 4 +- docs/{tev2 => }/terms/mrg-importer.md | 2 +- docs/{tev2 => }/terms/mrg.md | 6 +- docs/{tev2 => }/terms/mrgt.md | 8 +- .../terms/patterns/pattern-terminology.md | 12 +- docs/{tev2 => }/terms/property.md | 2 +- docs/{tev2 => }/terms/reader.md | 2 +- docs/{tev2 => }/terms/relation.md | 4 +- docs/{tev2 => }/terms/renderable-ref.md | 2 +- docs/{tev2 => }/terms/saf.md | 6 +- docs/{tev2 => }/terms/scope.md | 0 docs/{tev2 => }/terms/scoped-term.md | 0 docs/{tev2 => }/terms/scopedir.md | 0 docs/{tev2 => }/terms/scopetag.md | 0 docs/{tev2 => }/terms/semantics.md | 0 docs/{tev2 => }/terms/synonym.md | 0 docs/{tev2 => }/terms/tag.md | 0 docs/{tev2 => }/terms/term-identifier.md | 2 +- docs/{tev2 => }/terms/term-ref.md | 8 +- .../terms/term-selection-criteria.md | 10 +- docs/{tev2 => }/terms/term-syntax.md | 0 docs/{tev2 => }/terms/term-type.md | 0 docs/{tev2 => }/terms/term.md | 2 +- .../terms/terminological-artifact.md | 2 +- docs/{tev2 => }/terms/terminology-process.md | 2 +- .../terms/terminology-under-construction.md | 4 +- docs/{tev2 => }/terms/terminology.md | 4 +- docs/{tev2 => }/terms/terms-community.md | 0 docs/{tev2 => }/terms/tev2-tool.md | 4 +- docs/{tev2 => }/terms/tev2-toolbox.md | 8 +- docs/{tev2 => }/terms/tev2.md | 4 +- docs/{tev2 => }/terms/trrt.md | 2 +- docs/{tev2 => }/terms/versiontag.md | 0 docs/{tev2 => }/terms/vocabulary.md | 0 docs/{tev2 => }/tev2-glossary.md | 4 +- docs/{tev2 => }/tev2-overview.md | 10 +- docs/{tev2 => }/tev2-roles.md | 6 +- docs/{tev2 => }/tev2-spec-files.md | 10 +- docs/{tev2 => }/tev2-syntax.md | 6 +- docs/{tev2 => }/tev2-toolbox.md | 4 +- docs/tev2/23.2 | 0 docs/tev2/terms/@.md | 15 - docs/tev2/tev2-student-assignment.md | 42 --- docs/{tev2 => }/unique.py | 2 +- docs/{tev2 => }/unique_fields.xlsx | Bin docs/{tev2 => }/unique_py_specs.txt | 2 +- docs/{tev2 => }/zzz-broken-links-filter.rieks | 0 docs/{tev2 => }/zzz-tev2-tmscript.rieks | 2 +- docusaurus.config.js | 23 +- sidebars.js | 81 ++---- src/pages/index.js | 11 +- 149 files changed, 313 insertions(+), 1764 deletions(-) rename docs/{tev2 => }/README.md (67%) rename docs/{tev2 => }/glossaries/mrg.tev2.terms.yaml (96%) rename docs/{tev2 => }/manuals/author.md (100%) rename docs/{tev2 => }/manuals/contributor.md (100%) rename docs/{tev2 => }/manuals/contributors-latex.md (100%) rename docs/{tev2 => }/manuals/contributors-repo.md (100%) rename docs/{tev2 => }/manuals/contributors-wiki.md (100%) rename docs/{tev2 => }/manuals/curator.md (72%) rename docs/{tev2 => }/manuals/tev2-installation.md (83%) rename docs/{tev2 => }/miscellaneous/tool-development.md (61%) rename docs/{tev2 => }/mrgen.py (100%) rename docs/{tev2 => }/notations-and-conventions.md (100%) rename docs/{tev2 => }/overview/00-tev2-common-understanding.md (100%) rename docs/{tev2 => }/overview/10-tev2-purpose.md (89%) rename docs/{tev2 => }/overview/20-tev2-design-principles.md (71%) rename docs/{tev2 => }/overview/30-tev2-architecture.md (88%) rename docs/{tev2 => }/overview/40-tev2-terminology-curation.md (65%) rename docs/{tev2 => }/saf.yaml (91%) rename docs/{tev2 => }/showtexts-list.py (100%) rename docs/{tev2 => }/spec-files/00-ctext.md (90%) rename docs/{tev2 => }/spec-files/11-saf.md (96%) rename docs/{tev2 => }/spec-files/20-profile-templates.md (96%) rename docs/{tev2 => }/spec-files/21-mrg.md (93%) rename docs/{tev2 => }/spec-files/22-hrg.md (89%) rename docs/{tev2 => }/spec-files/51-mrd.md (100%) rename docs/{tev2 => }/spec-files/52-hrd.md (100%) rename docs/{tev2 => }/spec-files/ingestion.profile (92%) rename docs/{tev2 => }/spec-syntax/11-term-ref-syntax.md (95%) rename docs/{tev2 => }/spec-syntax/21-form-phrase-syntax.md (82%) rename docs/{tev2 => }/spec-syntax/31-hrg-termselcrit.md (91%) rename docs/{tev2 => }/spec-tools/11-ict.md (94%) rename docs/{tev2 => }/spec-tools/12-mrg-importer.md (89%) rename docs/{tev2 => }/spec-tools/13-trrt.md (90%) rename docs/{tev2 => }/spec-tools/20-terminology-construction.md (94%) rename docs/{tev2 => }/spec-tools/21-mrgt.md (75%) rename docs/{tev2 => }/spec-tools/22-hrgt-old.md (98%) rename docs/{tev2 => }/spec-tools/22-hrgt.md (93%) rename docs/{tev2 => }/spec-tools/31-mrdt.md (82%) rename docs/{tev2 => }/spec-tools/32-hrdt.md (97%) delete mode 100644 docs/terminology-design/backgrounds/expressing-oneself.md delete mode 100644 docs/terminology-design/backlog.md delete mode 100644 docs/terminology-design/manuals/authoring.md delete mode 100644 docs/terminology-design/manuals/contributing.md delete mode 100644 docs/terminology-design/manuals/curating.md delete mode 100644 docs/terminology-design/methods.md delete mode 100644 docs/terminology-design/methods/1-1-discussions.md delete mode 100644 docs/terminology-design/methods/criteria-elicitation.md delete mode 100644 docs/terminology-design/methods/real-life-example.md delete mode 100644 docs/terminology-design/methods/terminology-process.md delete mode 100644 docs/terminology-design/methods/why-design-thinking-works.txt delete mode 100644 docs/terminology-design/mrgen.py delete mode 100644 docs/terminology-design/overview.md delete mode 100644 docs/terminology-design/overview/00-common-understanding.md delete mode 100644 docs/terminology-design/overview/10-purpose.md delete mode 100644 docs/terminology-design/overview/20-design-principles.md delete mode 100644 docs/terminology-design/saf.yaml delete mode 100644 docs/terminology-design/terms/.concept-file.md delete mode 100644 docs/terminology-design/terms/author.md delete mode 100644 docs/terminology-design/terms/common-understanding.md delete mode 100644 docs/terminology-design/terms/domain-expert.md delete mode 100644 docs/terminology-design/terms/linguistic-unity.md rename docs/{terminology-design => }/terms/@.md (100%) rename docs/{tev2 => }/terms/_{termid}.mdx (99%) rename docs/{tev2 => }/terms/author.md (98%) rename docs/{tev2 => }/terms/body.md (97%) rename docs/{tev2 => }/terms/concept.md (100%) rename docs/{tev2 => }/terms/conceptualization.md (98%) rename docs/{tev2 => }/terms/converter.md (96%) rename docs/{tev2 => }/terms/corpus.md (100%) rename docs/{tev2 => }/terms/curate.md (97%) rename docs/{tev2 => }/terms/curated-text.md (91%) rename docs/{tev2 => }/terms/curatedir.md (100%) rename docs/{tev2 => }/terms/curator.md (98%) rename docs/{tev2 => }/terms/define.md (98%) rename docs/{tev2 => }/terms/definition.md (100%) rename docs/{tev2 => }/terms/dictionary.md (100%) rename docs/{tev2 => }/terms/formatted-text.md (98%) rename docs/{tev2 => }/terms/formphrase.md (97%) rename docs/{tev2 => }/terms/glossary.md (100%) rename docs/{tev2 => }/terms/glossarydir.md (100%) rename docs/{tev2 => }/terms/grouptag.md (100%) rename docs/{tev2 => }/terms/header.md (98%) rename docs/{tev2 => }/terms/hrd.md (96%) rename docs/{tev2 => }/terms/hrdt.md (93%) rename docs/{tev2 => }/terms/hrg-entry.md (86%) rename docs/{tev2 => }/terms/hrg.md (96%) rename docs/{tev2 => }/terms/hrgt.md (65%) rename docs/{tev2 => }/terms/ict.md (76%) rename docs/{tev2 => }/terms/identifier.md (100%) rename docs/{tev2 => }/terms/identify.md (100%) rename docs/{tev2 => }/terms/ingestion-process.md (87%) rename docs/{tev2 => }/terms/ingestion-profile.md (91%) rename docs/{tev2 => }/terms/interpreter.md (86%) rename docs/{tev2 => }/terms/knowledge-artifact.md (100%) rename docs/{tev2 => }/terms/mental-model.md (100%) rename docs/{tev2 => }/terms/moustache-variable.md (96%) rename docs/{tev2 => }/terms/mrd.md (97%) rename docs/{tev2 => }/terms/mrdt.md (93%) rename docs/{tev2 => }/terms/mrg-entry.md (90%) rename docs/{tev2 => }/terms/mrg-importer.md (97%) rename docs/{tev2 => }/terms/mrg.md (68%) rename docs/{tev2 => }/terms/mrgt.md (65%) rename docs/{tev2 => }/terms/patterns/pattern-terminology.md (85%) rename docs/{tev2 => }/terms/property.md (97%) rename docs/{tev2 => }/terms/reader.md (97%) rename docs/{tev2 => }/terms/relation.md (96%) rename docs/{tev2 => }/terms/renderable-ref.md (89%) rename docs/{tev2 => }/terms/saf.md (92%) rename docs/{tev2 => }/terms/scope.md (100%) rename docs/{tev2 => }/terms/scoped-term.md (100%) rename docs/{tev2 => }/terms/scopedir.md (100%) rename docs/{tev2 => }/terms/scopetag.md (100%) rename docs/{tev2 => }/terms/semantics.md (100%) rename docs/{tev2 => }/terms/synonym.md (100%) rename docs/{tev2 => }/terms/tag.md (100%) rename docs/{tev2 => }/terms/term-identifier.md (83%) rename docs/{tev2 => }/terms/term-ref.md (67%) rename docs/{tev2 => }/terms/term-selection-criteria.md (67%) rename docs/{tev2 => }/terms/term-syntax.md (100%) rename docs/{tev2 => }/terms/term-type.md (100%) rename docs/{tev2 => }/terms/term.md (95%) rename docs/{tev2 => }/terms/terminological-artifact.md (97%) rename docs/{tev2 => }/terms/terminology-process.md (99%) rename docs/{tev2 => }/terms/terminology-under-construction.md (91%) rename docs/{tev2 => }/terms/terminology.md (83%) rename docs/{tev2 => }/terms/terms-community.md (100%) rename docs/{tev2 => }/terms/tev2-tool.md (94%) rename docs/{tev2 => }/terms/tev2-toolbox.md (87%) rename docs/{tev2 => }/terms/tev2.md (92%) rename docs/{tev2 => }/terms/trrt.md (96%) rename docs/{tev2 => }/terms/versiontag.md (100%) rename docs/{tev2 => }/terms/vocabulary.md (100%) rename docs/{tev2 => }/tev2-glossary.md (75%) rename docs/{tev2 => }/tev2-overview.md (55%) rename docs/{tev2 => }/tev2-roles.md (92%) rename docs/{tev2 => }/tev2-spec-files.md (50%) rename docs/{tev2 => }/tev2-syntax.md (50%) rename docs/{tev2 => }/tev2-toolbox.md (94%) delete mode 100644 docs/tev2/23.2 delete mode 100644 docs/tev2/terms/@.md delete mode 100644 docs/tev2/tev2-student-assignment.md rename docs/{tev2 => }/unique.py (98%) rename docs/{tev2 => }/unique_fields.xlsx (100%) rename docs/{tev2 => }/unique_py_specs.txt (98%) rename docs/{tev2 => }/zzz-broken-links-filter.rieks (100%) rename docs/{tev2 => }/zzz-tev2-tmscript.rieks (98%) diff --git a/docs/tev2/README.md b/docs/README.md similarity index 67% rename from docs/tev2/README.md rename to docs/README.md index c7d44cc4d5..4173b24a13 100644 --- a/docs/tev2/README.md +++ b/docs/README.md @@ -8,11 +8,11 @@ date: 20220402 # Contributing to TEv2 Tools :::info Editor's note -This documentation is based on the [ToIP TT-Tools Proposal](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2/toip-terminology-toolbox) memo, which we currently keep as a reference. +This documentation is based on the [ToIP TT-Tools Proposal](https://tno-terminology-design.github.io/tev2-specifications/docs/toip-terminology-toolbox) memo, which we currently keep as a reference. ::: -The '[Terminology Engine v2 (TEv2)](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2/tev2-overview)' consists of two parts: -1. The [Terminology Toolbox](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2/tev2-toolbox) is a set of (extendable) command-line tools that can be used for generic purposes, such as resolving [TermReferences](term-ref@), and creating glossaries. +The '[Terminology Engine v2 (TEv2)](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2-overview)' consists of two parts: +1. The [Terminology Toolbox](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2-toolbox) is a set of (extendable) command-line tools that can be used for generic purposes, such as resolving [TermReferences](term-ref@), and creating glossaries. 2. The use of these, and other tools (in our case: [Docusaurus](https://docusaurus.io/), and [github CI/CD](https://resources.github.com/ci-cd/)), for facilitating the [curation](curate@) of [terminologies](terminology@) by [terms communities](terms-community@). We are seeking parties that can contribute to the development of these (extendable) command-line tools, and do so in close collaboration with the eSSIF-Lab consortium. Please express your interest as an [issue in the eSSIF-Lab repo](https://github.com/tno-terminology-design/tev2-specifications/issues). \ No newline at end of file diff --git a/docs/tev2/glossaries/mrg.tev2.terms.yaml b/docs/glossaries/mrg.tev2.terms.yaml similarity index 96% rename from docs/tev2/glossaries/mrg.tev2.terms.yaml rename to docs/glossaries/mrg.tev2.terms.yaml index a006efd6af..4a7e90816e 100644 --- a/docs/tev2/glossaries/mrg.tev2.terms.yaml +++ b/docs/glossaries/mrg.tev2.terms.yaml @@ -1,10 +1,10 @@ terminology: scopetag: tev2 scopedir: - https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/tev2 + https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs curatedir: terms glossarydir: glossaries - website: https://tno-terminology-design.github.io/tev2-specifications/docs/tev2 + website: https://tno-terminology-design.github.io/tev2-specifications/docs navpath: /terms license: LICENSE.md version: terms @@ -47,7 +47,7 @@ entries: updated: 20230723 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /author @@ -74,7 +74,7 @@ entries: updated: 20230723 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /body @@ -137,7 +137,7 @@ entries: updated: 20230723 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /conceptualization @@ -168,7 +168,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /converter @@ -222,7 +222,7 @@ entries: updated: 20230723 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /curate @@ -301,7 +301,7 @@ entries: updated: 20230723 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /curator @@ -331,7 +331,7 @@ entries: updated: 20230723 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /define @@ -415,7 +415,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /formatted-text @@ -444,7 +444,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /form-phrase @@ -554,7 +554,7 @@ entries: updated: 20230723 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /header @@ -587,7 +587,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /hrd @@ -614,7 +614,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /hrdt @@ -641,7 +641,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /hrg-entry @@ -670,7 +670,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /hrg @@ -685,7 +685,7 @@ entries: isa: tool glossaryTerm: Human Readable Glossary Tool (HRGT) glossaryText: a software tool designed to create, manage, and process [Human Readable - Glossaries (HRGs)](@), as [specified by TEv2](/docs/tev2/spec-tools/hrgt). HRGTs + Glossaries (HRGs)](@), as [specified by TEv2](/docs/spec-tools/hrgt). HRGTs offer features for selecting [terms](@) that are [curated](@) within the [scope](@) it is run in, or from other [scopes](@). hoverText: 'HRGT: {(noRef {glossaryText})}' @@ -698,7 +698,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /hrgt @@ -715,7 +715,7 @@ entries: glossaryText: a software tool designed to check the integrity and conformity of various files used in the curation and management of [glossaries](@), [dictionaries](@), [curated texts](@), and other data within a terminology project. The ICT verifies - that the files adhere to the [TEv2 file specifications](/docs/tev2/tev2-spec-files), + that the files adhere to the [TEv2 file specifications](/docs/tev2-spec-files), ensuring the consistency and accuracy of the terminology data. hoverText: 'Integrity Checker Tool (ICT): {(noRef {glossaryText})}' synonymOf: integrity-checker @@ -727,7 +727,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /ict @@ -802,7 +802,7 @@ entries: members suggest, draft, and discuss [definitions](@) ([terms](@) + [criteria](@)) that are relevant for a particular [scope](@), and converting such contributions into [curated texts](@) that accurately document the [concepts](@) and other - [terminologic artifacts](@) and that adhere to the [TEv2-specifications](/docs/tev2/spec-files/ctext). + [terminologic artifacts](@) and that adhere to the [TEv2-specifications](/docs/spec-files/ctext). hoverText: 'Ingestion Process: {(noRef {glossaryText})}' synonymOf: grouptags: @@ -813,7 +813,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /ingestion @@ -869,7 +869,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /interpreter @@ -953,7 +953,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /moustache-variable @@ -981,7 +981,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /mrd @@ -1009,7 +1009,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /mrdt @@ -1064,7 +1064,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /mrg-importer @@ -1081,7 +1081,7 @@ entries: isa: glossary glossaryTerm: Machine Readable Glossary (MRG) glossaryText: a [glossary](@) for a particular (version of a) [terminology](@) - that is formatted in YAML, according to the [TEv2 MRG specifications](/docs/tev2/spec-files/mrg), + that is formatted in YAML, according to the [TEv2 MRG specifications](/docs/spec-files/mrg), to enable automated processing and integration with software systems. hoverText: 'MRG: {(noRef {glossaryText})}' synonymOf: @@ -1093,7 +1093,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /mrg @@ -1108,7 +1108,7 @@ entries: isa: tool glossaryTerm: Machine Readable Glossary Tool (MRGT) glossaryText: a software tool designed to create, manage, and process [Machine - Readable Glossaries (MRGs)](@), as [specified by TEv2](/docs/tev2/spec-tools/mrgt). + Readable Glossaries (MRGs)](@), as [specified by TEv2](/docs/spec-tools/mrgt). MRGTs offer features for selecting [terms](@) that are [curated](@) within the [scope](@) it is run in, or from other [scopes](@). hoverText: 'MRGT: {(noRef {glossaryText})}' @@ -1121,7 +1121,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /mrgt @@ -1148,7 +1148,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /property @@ -1177,7 +1177,7 @@ entries: updated: 20230723 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /reader @@ -1204,7 +1204,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /relation @@ -1262,7 +1262,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /saf @@ -1482,7 +1482,7 @@ entries: termType: concept isa: glossaryTerm: TermRef - glossaryText: a word or phrase that is [marked up (in a specific way)](/docs/tev2/spec-syntax/term-ref-syntax) + glossaryText: a word or phrase that is [marked up (in a specific way)](/docs/spec-syntax/term-ref-syntax) so that it refers to a particular [concept](@) (or other [knowledge artifact](@)), enabling it to be rendered in a variety of ways for the purpose of helping [readers](@) to (better) understand the intention of its [author](@). @@ -1523,7 +1523,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /term-selection-criteria @@ -1626,7 +1626,7 @@ entries: created: 2023-07-31 updated: 2023-07-31 contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /terminological-artifact @@ -1652,7 +1652,7 @@ entries: updated: 20230723 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /terminology-process @@ -1684,7 +1684,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /terminology-under-construction @@ -1764,7 +1764,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /tev2-tool @@ -1782,7 +1782,7 @@ entries: isa: definition glossaryTerm: TEv2 Toolbox glossaryText: the collection of tools designed to support and facilitate the process - of terminology management following the [TEv2 specifications](/docs/tev2/overview). + of terminology management following the [TEv2 specifications](/docs/overview). These tools assist [curators](@) in various tasks related to the curation, creation, and maintenance of terminological assets. hoverText: 'TEv2 Toolbox: {(noRef {glossaryText})}' @@ -1795,7 +1795,7 @@ entries: updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /tev2-toolbox @@ -1847,7 +1847,7 @@ entries: created: 2023-07-31 updated: 2023-07-31 contributors: RieksJ - attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)' + attribution: '[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)' originalLicense: '[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)' scopetag: tev2 locator: /trrt diff --git a/docs/tev2/manuals/author.md b/docs/manuals/author.md similarity index 100% rename from docs/tev2/manuals/author.md rename to docs/manuals/author.md diff --git a/docs/tev2/manuals/contributor.md b/docs/manuals/contributor.md similarity index 100% rename from docs/tev2/manuals/contributor.md rename to docs/manuals/contributor.md diff --git a/docs/tev2/manuals/contributors-latex.md b/docs/manuals/contributors-latex.md similarity index 100% rename from docs/tev2/manuals/contributors-latex.md rename to docs/manuals/contributors-latex.md diff --git a/docs/tev2/manuals/contributors-repo.md b/docs/manuals/contributors-repo.md similarity index 100% rename from docs/tev2/manuals/contributors-repo.md rename to docs/manuals/contributors-repo.md diff --git a/docs/tev2/manuals/contributors-wiki.md b/docs/manuals/contributors-wiki.md similarity index 100% rename from docs/tev2/manuals/contributors-wiki.md rename to docs/manuals/contributors-wiki.md diff --git a/docs/tev2/manuals/curator.md b/docs/manuals/curator.md similarity index 72% rename from docs/tev2/manuals/curator.md rename to docs/manuals/curator.md index 714b358a1f..972a4adf70 100644 --- a/docs/tev2/manuals/curator.md +++ b/docs/manuals/curator.md @@ -28,19 +28,19 @@ The task of [curators](@) is to create/maintain the [scope directory](@) that th This section needs to be revised from here onward ::: -TEv2 assumes that the [curated](@) data resides in an existing [scope directory](@), and that [curated files](@) are expected to be processable by other tools, including, but not limited to [github pages](https://pages.github.com/) or [Docusaurus](https://docusaurus.io/docs/docs-introduction), which are static site generators for web sites that document all sorts of guidance, specifications, etc. Such a [scope directory](@) must be [set up](/docs/tev2/manuals/tev2-installation) in advance. +TEv2 assumes that the [curated](@) data resides in an existing [scope directory](@), and that [curated files](@) are expected to be processable by other tools, including, but not limited to [github pages](https://pages.github.com/) or [Docusaurus](https://docusaurus.io/docs/docs-introduction), which are static site generators for web sites that document all sorts of guidance, specifications, etc. Such a [scope directory](@) must be [set up](/docs/manuals/tev2-installation) in advance. Thus, whenever a [terms-community](@) decided that some contribution is to be included in the part of the [corpus](@) that is maintained by that [community](terms-community@), the [curators](@) of that [community](terms-community@) are tasked to -1. create/maintain/update any [scope](@)-related administration in the [scope directory](@) that is needed for curation, as specified by a [Scope Administration File (SAF)]/tev2/spec-files/saf; -2. convert that contribution to (a set of) [curated files](@), that comply with the [specifications](/docs/tev2/spec-files/ctext) for such files; -3. store them at the location as designated in the [SAF]/tev2/spec-files/saf; +1. create/maintain/update any [scope](@)-related administration in the [scope directory](@) that is needed for curation, as specified by a [Scope Administration File (SAF)](docs/spec-files/saf); +2. convert that contribution to (a set of) [curated files](@), that comply with the [specifications](/docs/spec-files/ctext) for such files; +3. store them at the location as designated in the [SAF](docs/spec-files/saf); 4. generate/update any artifact that the [community](terms-community@) wants to automatically maintain, which in particular includes the [MRG](@) and associated [HRG](@). This document provides an overview of the knowledge that [curators](@) may need to perform this task, which can be broken up in the following parts: -1. [Setup/installation](/docs/tev2/manuals/tev2-installation) of a [scope directory](@) that is suitable for working with TEv2, and the creation of a [SAF]/tev2/spec-files/saf. +1. [Setup/installation](/docs/manuals/tev2-installation) of a [scope directory](@) that is suitable for working with TEv2, and the creation of a [SAF](docs/spec-files/saf). -2. [Curation](@) of terminological contributions. This requires knowledge about the [file structure](/docs/tev2/spec-files/ctext) of [curated file](@). +2. [Curation](@) of terminological contributions. This requires knowledge about the [file structure](/docs/spec-files/ctext) of [curated file](@). -3. [generation](/docs/tev2/tev2-toolbox) of [curated texts](@). It is typical for a [terms community](@) to want to have a [glossary](@) of the [terms](@) they either have [defined](@) themselves, or are [defined](@) elsewhere but are to be used within that [community](@). However, other artifacts may be generated as well (a [dictionary](@), white papers, etc.) - this is all up to the [community](@). \ No newline at end of file +3. [generation](/docs/tev2-toolbox) of [curated texts](@). It is typical for a [terms community](@) to want to have a [glossary](@) of the [terms](@) they either have [defined](@) themselves, or are [defined](@) elsewhere but are to be used within that [community](@). However, other artifacts may be generated as well (a [dictionary](@), white papers, etc.) - this is all up to the [community](@). \ No newline at end of file diff --git a/docs/tev2/manuals/tev2-installation.md b/docs/manuals/tev2-installation.md similarity index 83% rename from docs/tev2/manuals/tev2-installation.md rename to docs/manuals/tev2-installation.md index 8b20b1c733..3e1f55bda3 100644 --- a/docs/tev2/manuals/tev2-installation.md +++ b/docs/manuals/tev2-installation.md @@ -29,9 +29,9 @@ This page should only document the generic stuff. Any installation details that TEv2 is a tool for [curating](@) [terminology](@)-related data from the perspective of a single [scope](@). Installation comprises - setting up, or appointing an (online) directory that will serve as a [scope directory](@); -- creating a [Scope Administration File (SAF)]/tev2/spec-files/saf, and providing the configuration of the [scope](@) and its [terminology](@); -- installing the [tev2-toolbox](/docs/tev2/tev2-toolbox); -- integrating the [tools](/docs/tev2/tev2-toolbox) with other tools, such as a CI/CD pipeline on github or gitlab, static site generators such as [github pages](https://pages.github.com/) or [Docusaurus](https://docusaurus.io/docs/docs-introduction), etc. See also: [Using the Tools](/docs/tev2/tev2-toolbox). +- creating a [Scope Administration File (SAF)](docs/spec-files/saf), and providing the configuration of the [scope](@) and its [terminology](@); +- installing the [tev2-toolbox](/docs/tev2-toolbox); +- integrating the [tools](/docs/tev2-toolbox) with other tools, such as a CI/CD pipeline on github or gitlab, static site generators such as [github pages](https://pages.github.com/) or [Docusaurus](https://docusaurus.io/docs/docs-introduction), etc. See also: [Using the Tools](/docs/tev2-toolbox). ### Structure of Scope Directories diff --git a/docs/tev2/miscellaneous/tool-development.md b/docs/miscellaneous/tool-development.md similarity index 61% rename from docs/tev2/miscellaneous/tool-development.md rename to docs/miscellaneous/tool-development.md index 43cacc1ddf..3cdc247e9b 100644 --- a/docs/tev2/miscellaneous/tool-development.md +++ b/docs/miscellaneous/tool-development.md @@ -13,12 +13,12 @@ This page intends to provide (lots of pointers to) information that people may n ## What it is about -At the core of [TEv2](@) is [text conversion](/docs/tev2/overview/tev2-design-principles): every [tool in the toolbox](/docs/tev2/tev2-toolbox) takes one or more input files, does some textual processing, and produces outputs. The basic [conversion pattern](/docs/tev2/overview/tev2-design-principles#text-conversion-steps) that individual [tools](/docs/tev2/tev2-toolbox) are expected to follow ensures that they can be easily extended, e.g., to operate on different input formats, or to produce alternative output formats. +At the core of [TEv2](@) is [text conversion](/docs/overview/tev2-design-principles): every [tool in the toolbox](/docs/tev2-toolbox) takes one or more input files, does some textual processing, and produces outputs. The basic [conversion pattern](/docs/overview/tev2-design-principles#text-conversion-steps) that individual [tools](/docs/tev2-toolbox) are expected to follow ensures that they can be easily extended, e.g., to operate on different input formats, or to produce alternative output formats. There are various things that make the further development of [TEv2](@) challenging: -1. the interop between individual tools: outputs of one tool must be fit for processing by another tool (which may include existing third party tools, such as static website generators), as described in the [TEv2 Architecture](/docs/tev2/overview/tev2-architecture). -2. designing actual tools such that they can be easily extended (also by others) to accept different input formats, and/or produce different output formats, as described in the [text conversion steps pattern](/docs/tev2/overview/tev2-design-principles#text-conversion-steps) +1. the interop between individual tools: outputs of one tool must be fit for processing by another tool (which may include existing third party tools, such as static website generators), as described in the [TEv2 Architecture](/docs/overview/tev2-architecture). +2. designing actual tools such that they can be easily extended (also by others) to accept different input formats, and/or produce different output formats, as described in the [text conversion steps pattern](/docs/overview/tev2-design-principles#text-conversion-steps) 3. designing tools such that they can be easily used in different contexts (e.g. whether or not to dockerize a tool) 4. collaborating with other people that work on the tools such that the coherence and consistent working of tools that different people develop is guaranteed. We may need to better organize this. 5. making the tools automatically testable, e.g. by running test suites as part of the CI/CD street we envisage that tools would have. @@ -33,11 +33,11 @@ There are various things that make the further development of [TEv2](@) challeng :::info In order to appreciate and come to grips with these challenges, it will definitely help if you read up on some more backgrounds of what we try to do. Here are some pointers: -- The [TEv2 Overview](/docs/tev2/tev2-overview) (and its sub-documents) will provide you with with such backgrounds. +- The [TEv2 Overview](/docs/tev2-overview) (and its sub-documents) will provide you with with such backgrounds. - Other documented topics include: - - [file structure spec](/docs/tev2/tev2-spec-files) - - [syntax specifications](/docs/tev2/tev2-syntax) - - [specifications of individual tools](/docs/tev2/tev2-toolbox) - not all specifications hare already been drafted/checked. + - [file structure spec](/docs/tev2-spec-files) + - [syntax specifications](/docs/tev2-syntax) + - [specifications of individual tools](/docs/tev2-toolbox) - not all specifications hare already been drafted/checked. ::: ## Tooling status as of ... @@ -46,19 +46,19 @@ For the date of the tooling status, see the "last updated on" text at the ### Under development -- [MRGT](/docs/tev2/spec-tools/mrgt), which is in [this toip repo](https://github.com/trustoverip/ctwg-toolkit-mrg). The tool works, but still has some [bugs/issues](https://github.com/trustoverip/ctwg-toolkit-mrg/issues) that need to be fixed. -- [TRRT](/docs/tev2/spec-tools/trrt), which is currently actively developed by TNO in [this repo](https://github.com/tno-terminology-design/trrt). +- [MRGT](/docs/spec-tools/mrgt), which is in [this toip repo](https://github.com/trustoverip/ctwg-toolkit-mrg). The tool works, but still has some [bugs/issues](https://github.com/trustoverip/ctwg-toolkit-mrg/issues) that need to be fixed. +- [TRRT](/docs/spec-tools/trrt), which is currently actively developed by TNO in [this repo](https://github.com/tno-terminology-design/trrt). ### High priority -- ingress tools that convert wiki-files (and perhaps some other formats) into [curated texts](/docs/tev2/spec-files/00-ctext.md); -- [HRGT](/docs/tev2/spec-tools/hrgt), so that we can actually generate human-readable glossaries. For this tool, specifications need to be further drafted (and agreed on). +- ingress tools that convert wiki-files (and perhaps some other formats) into [curated texts](/docs/spec-files/00-ctext.md); +- [HRGT](/docs/spec-tools/hrgt), so that we can actually generate human-readable glossaries. For this tool, specifications need to be further drafted (and agreed on). ### Medium priority: -- [ICT](/docs/tev2/spec-tools/ict), which allows for integrity checking. The current specifications are outdated and first need to be revised. +- [ICT](/docs/spec-tools/ict), which allows for integrity checking. The current specifications are outdated and first need to be revised. ### Lower priority: - extensions for the [TRRT](@), and perhaps other tools, so that they can be used in [ReSpec](https://dev.w3.org/2008/video/mediaann/ReSpec.js/documentation.html) environments, such as often used for W3C standards. -- [MRDT](/docs/tev2/spec-tools/mrdt) and [HRDT](/docs/tev2/spec-tools/hrdt) +- [MRDT](/docs/spec-tools/mrdt) and [HRDT](/docs/spec-tools/hrdt) ## Starting to contribute diff --git a/docs/tev2/mrgen.py b/docs/mrgen.py similarity index 100% rename from docs/tev2/mrgen.py rename to docs/mrgen.py diff --git a/docs/tev2/notations-and-conventions.md b/docs/notations-and-conventions.md similarity index 100% rename from docs/tev2/notations-and-conventions.md rename to docs/notations-and-conventions.md diff --git a/docs/tev2/overview/00-tev2-common-understanding.md b/docs/overview/00-tev2-common-understanding.md similarity index 100% rename from docs/tev2/overview/00-tev2-common-understanding.md rename to docs/overview/00-tev2-common-understanding.md diff --git a/docs/tev2/overview/10-tev2-purpose.md b/docs/overview/10-tev2-purpose.md similarity index 89% rename from docs/tev2/overview/10-tev2-purpose.md rename to docs/overview/10-tev2-purpose.md index ba0b0b92b2..d74a03a7ed 100644 --- a/docs/tev2/overview/10-tev2-purpose.md +++ b/docs/overview/10-tev2-purpose.md @@ -17,13 +17,13 @@ As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', The Terminology Engine (v2) is a set of specifications and tools that caters for the creation and maintenance (i.e. [curation](@)) of [terminologies](@), as well as for its subsequent use in publications of different types (e.g. websites, whitepapers) and formats (e.g. html, LaTeX), as appropriate for different, individual [scopes](@). -The main objective of [TEv2](@) is to provide support to [communities](@) that actively seek to [understand one another](/docs/tev2/overview/tev2-common-understanding), first within the [community](@) itself, but also across [communities](@) that also use [TEv2](@). +The main objective of [TEv2](@) is to provide support to [communities](@) that actively seek to [understand one another](/docs/overview/tev2-common-understanding), first within the [community](@) itself, but also across [communities](@) that also use [TEv2](@). In practice, this means that [TEv2](@) provides tools and mechanisms that: 1. help [readers](@) of publications (that were generated with [TEv2](@) tools) to understand the [terms](@) that are used therein, in the way that the [authors](@) have intended (rather than interpreting such [terms](@) in their own way); 2. facilitating [authors](@) to write and publish texts where terms can be referenced to their intended meaning, within, and across [scopes](@); 3. supporting [authors](@), [readers](@) and other stakeholders to such publications as they seek to create and further develop a [terminology](@) that they can commit to (within a specific [scope](@)), which we expect to also help develop insights in their subject matter of that [scope](@)). -These contributions are what so-called [curators](@) of the [scope](@) seek to deliver. They are the ones that make sure that there is a [location](scopedir@) where people can contribute to the development of the [terminology](@) of a [scope](@), and tools are installed and operational that enable [authors](@) to use them as they publish their documents. [Curators](@) have their own [manual](/docs/tev2/manuals/curator). +These contributions are what so-called [curators](@) of the [scope](@) seek to deliver. They are the ones that make sure that there is a [location](scopedir@) where people can contribute to the development of the [terminology](@) of a [scope](@), and tools are installed and operational that enable [authors](@) to use them as they publish their documents. [Curators](@) have their own [manual](/docs/manuals/curator). The [eSSIF-Lab website](/docs/essifLab) already shows the first ideas of what that might look like (popups on [terms](@) showing their [definition](@)). diff --git a/docs/tev2/overview/20-tev2-design-principles.md b/docs/overview/20-tev2-design-principles.md similarity index 71% rename from docs/tev2/overview/20-tev2-design-principles.md rename to docs/overview/20-tev2-design-principles.md index e4feb0ce78..0f618faede 100644 --- a/docs/tev2/overview/20-tev2-design-principles.md +++ b/docs/overview/20-tev2-design-principles.md @@ -19,7 +19,7 @@ As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', ## Text Conversion -The (documentary) artifacts we envisage are typically in the form of e.g. a (static) website, or documents in formats such as PDF, ODT, DOCX, etc., that is: in an arbitrary form that is readable for humans. However, they are typically (but not always) authored in much simpler, raw formats, such as plain ASCII text, markdown, LaTeX, etc., and one or more conversion steps are required to turn these 'raw texts' into nicely 'rendered texts'. [TEv2](@) specifies a set of tools (a '[toolbox](/docs/tev2/tev2-toolbox)') that can be used in the conversion process, as illustrated (in a simplified way) in the figure below: +The (documentary) artifacts we envisage are typically in the form of e.g. a (static) website, or documents in formats such as PDF, ODT, DOCX, etc., that is: in an arbitrary form that is readable for humans. However, they are typically (but not always) authored in much simpler, raw formats, such as plain ASCII text, markdown, LaTeX, etc., and one or more conversion steps are required to turn these 'raw texts' into nicely 'rendered texts'. [TEv2](@) specifies a set of tools (a '[toolbox](/docs-toolbox)') that can be used in the conversion process, as illustrated (in a simplified way) in the figure below:

Figure 1: Converting raw texts into formatted texts and curated texts

-Many things that can be done with tools in the [toolbox](/docs/tev2/tev2-toolbox), such as the generation of [glossaries](@) or [dictionaries](@), the contents of which can be tailored, and they can be rendered in various formats. The toolbox has been designed to be extensible, which means that if at one point in time some tailoring or rendering features are missing, they can be added later, as needed. +Many things that can be done with tools in the [toolbox](/docs-toolbox), such as the generation of [glossaries](@) or [dictionaries](@), the contents of which can be tailored, and they can be rendered in various formats. The toolbox has been designed to be extensible, which means that if at one point in time some tailoring or rendering features are missing, they can be added later, as needed. -A particularly nice feature of the [toolbox](/docs/tev2/tev2-toolbox) is its capability of working with so-called [TermRefs](@), which are pieces of text that are [annotated](/docs/tev2/spec-syntax/term-ref-syntax) to refer to a particular [term](@), the effect of which in the rendered version of the text can help [readers](@) understand the meaning in which the [term](@) was used. The figure below shows an example of this: at the left you see a raw (markdown) text, where the terms **`community`**, **`own`** and **`terminology`** have been annotated to refer to [curated](@) [terms](@) (from specific [scopes](@)). At the right side you see the effect that tools from the [toolbox](/docs/tev2/tev2-toolbox) and other third party tools had as they rendered this text into an (HTML) web page: the texts are highlighted, and when the [reader](@) hovers its mouse over that text, a popup-balloon shows that contains the definition of the [term](@) that was referenced. +A particularly nice feature of the [toolbox](/docs-toolbox) is its capability of working with so-called [TermRefs](@), which are pieces of text that are [annotated](/docs/spec-syntax/term-ref-syntax) to refer to a particular [term](@), the effect of which in the rendered version of the text can help [readers](@) understand the meaning in which the [term](@) was used. The figure below shows an example of this: at the left you see a raw (markdown) text, where the terms **`community`**, **`own`** and **`terminology`** have been annotated to refer to [curated](@) [terms](@) (from specific [scopes](@)). At the right side you see the effect that tools from the [toolbox](/docs-toolbox) and other third party tools had as they rendered this text into an (HTML) web page: the texts are highlighted, and when the [reader](@) hovers its mouse over that text, a popup-balloon shows that contains the definition of the [term](@) that was referenced.

TEv2 OverviewThe [`term`-field](/docs/tev2/spec-syntax/term-ref-syntax#term) of a [TermRef](@) that refers to this [curated text](@) must match this value.
Must satisfy regex `[a-z0-9_-]+`. | +| `term` | Y | [Text](term-identifier@) that [identifies](@) a [knowledge artifact](@) within this [scope](@), and hence also the [curated text](@) that describes it, which includes its [definition](@). Its value is typically the value of the `glossaryTerm` field, where all characters are made lower-case, any text between parentheses is discarded, and any (sequences of) spaces (or other special characters) are replaced with a `-`character.
The [`term`-field](/docs/spec-syntax/term-ref-syntax#term) of a [TermRef](@) that refers to this [curated text](@) must match this value.
Must satisfy regex `[a-z0-9_-]+`. | | `termType` | n | [Text](term-type@) that [identifies](@) the kind of [knowledge artifact](@) that this [curated text](@) describes. Typical values would be `concept`, `relation`, `pattern` (or `mental-model`), `term` (or `alias`), or `usecase`.
Must satisfy regex `[a-z0-9_-]+`. | | `isa` | n | [knowledge artifact](@) of which this is a specialization. | | `glossaryTerm` | n | Text that is used for the [term](@) in a human readable [glossary](@). For example, for a [term](@) called `member`, you may want to specify a glossaryTerm `member (of a [community](@))`. | | `glossaryText` | n | Text that is used as the (raw) contents for the entry of this [term](@) in a human readable [glossary](@). This text MUST be expected to contain [TermRefs](@). | | `synonymOf` | n | [term identifier](@) that [identifies](@) the defined [term](@) of the [terminological artifact](@) for which this is a [synonym](@). | | `grouptags` | n | List of [grouptags](@), each of which signifies that the [(scoped) term](@) that this [curated text](@) documents, is part of the group of [terms](@) that it represents.
Example: `[tev2, management]`.
Must satisfy regex [`(?:\[\s*([a-z0-9_-]+)\s*(?:,\s*([a-z0-9_-]+))*\s*\])?`](https://www.debuggex.com/r/a51CXl1NzR3kwihT). | -| `formPhrases` | n | List of [texts](formphrase@) that are [used to convert](/docs/tev2/spec-tools/trrt#id) the `show text` parts of [TermRefs](@) into `term`s, for the purpose of accommodating plural forms (for nouns) or conjugate forms (for verbs). For details, see ['Syntax Specs - Form Phrases](/docs/tev2/spec-syntax/form-phrase-syntax). | +| `formPhrases` | n | List of [texts](formphrase@) that are [used to convert](/docs/spec-tools/trrt#id) the `show text` parts of [TermRefs](@) into `term`s, for the purpose of accommodating plural forms (for nouns) or conjugate forms (for verbs). For details, see ['Syntax Specs - Form Phrases](/docs/spec-syntax/form-phrase-syntax). | | `status` | n | Text that identifies the status of the term. ([Communities](@) of) [scopes](@) may specify values for this field. An example is the [status tags used by ToIP](https://github.com/trustoverip/concepts-and-terminology-wg/blob/master/docs/status-tags.md). | | `created` | n | Date at which of the [curated text](@) was created, in the date format as used within this [scope](@). | | `updated` | n | Date at which of the [curated text](@) was last modified, in the date format as used within this [scope](@). | diff --git a/docs/tev2/spec-files/11-saf.md b/docs/spec-files/11-saf.md similarity index 96% rename from docs/tev2/spec-files/11-saf.md rename to docs/spec-files/11-saf.md index 760a053c7e..7ac2ad4f33 100644 --- a/docs/tev2/spec-files/11-saf.md +++ b/docs/spec-files/11-saf.md @@ -48,14 +48,14 @@ The following sections specify the fields for each of these parts. # scope: scopetag: tev2 # identifier that curators have determined for this terminology - scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/tev2 # URL of the scope-directory + scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs # URL of the scope-directory curatedir: terms # directory where all curated files are located. Full URL is `scopedir`/`curatedir` glossarydir: glossaries # directory where all glossary files and related stuff are located. Full URL is `scopedir`/`glossarydir` defaultvsn: latest # vsntag that identifies the default terminology. MRG is located at `scopedir`/`glossarydir`/mrg.`scopetag`.`defaultvsn`.yaml license: LICENSE.md # file that contains the (default) licensing conditions. Full URL is `scopedir`/`license` statuses: [ proposed, approved, deprecated ] # list of status tags that are defined for knowledge artifacts in this scope issues: https://github.com/tno-terminology-design/tev2-specifications/issues # URL where issues can be raised and handled - website: https://tno-terminology-design.github.io/tev2-specifications/docs/tev2/tev2-overview # base URL for creating links to rendered versions of Curated Texts + website: https://tno-terminology-design.github.io/tev2-specifications/docs-overview # base URL for creating links to rendered versions of Curated Texts curators: # contacting individual curators - name: RieksJ email: # we split up the email address to reduce the likelihood of the address being harvested for spamming @@ -193,11 +193,11 @@ The following fields are defined for the `versions` section of a [SAF](@): | `vsntag` | Y | [Versiontag](@) that that is used to [identify](@) this version within the set of all other versions that are maintained within this [scope](@). in this [SAF](@). It MUST NOT be changed during the lifetime of this version.
Must satisfy regex `[a-z0-9_-\.]+`. | | `altvsntags` | n | List of alternative [versiontags](@) that may be used to refer to this version of the [scope's](@) [terminology](@). A typical use of this field would be to tag a version as the 'latest' version.
Must satisfy regex `[a-z0-9_-\.]+`. | | `license` | n | File that contains the (default) licensing conditions. Full URL is `scopedir`/`license`. If not specified, its value defaults to the value of the `license` field in the `scope` section (of this [SAF](@)). The purpose of this field is to allow different versions of the [scope's](@) [terminology](@) to have different licenses. | -| `termselcrit` | Y | List of [term selection criteria](@) that are used to generate (this version of) the [scope's](@) [terminology](@). See [Terminology Construction](/docs/tev2/spec-tools/terminology-construction) for details. | +| `termselcrit` | Y | List of [term selection criteria](@) that are used to generate (this version of) the [scope's](@) [terminology](@). See [Terminology Construction](/docs/spec-tools/terminology-construction) for details. | | `status` | n | Text that [identifies](@) the status of the [term](@). ([Communities](@) of) [scopes](@) may specify values for this field. If not specified, the status SHOULD be assumed to be 'concept', 'draft', 'proposed', or similar. An example is the [status tags used by ToIP](https://github.com/trustoverip/concepts-and-terminology-wg/blob/master/docs/status-tags.md). | | `from` | F | Date at which it was decided to establish this version. | | `to` | F | Date at which this version will expire (or has expired). | :::info Editor's note -The `from` and `to` dates have been included to (in future) enable one to refer to a specific version of the terminology that was valid at a particular date. This feature needs to be worked out, and will impact [terminology construction](/docs/tev2/spec-tools/terminology-construction), [TermRef specs](/docs/tev2/spec-syntax/term-ref-syntax), and various tools. +The `from` and `to` dates have been included to (in future) enable one to refer to a specific version of the terminology that was valid at a particular date. This feature needs to be worked out, and will impact [terminology construction](/docs/spec-tools/terminology-construction), [TermRef specs](/docs/spec-syntax/term-ref-syntax), and various tools. ::: diff --git a/docs/tev2/spec-files/20-profile-templates.md b/docs/spec-files/20-profile-templates.md similarity index 96% rename from docs/tev2/spec-files/20-profile-templates.md rename to docs/spec-files/20-profile-templates.md index 8bb124d1a6..8e6361795f 100644 --- a/docs/tev2/spec-files/20-profile-templates.md +++ b/docs/spec-files/20-profile-templates.md @@ -32,7 +32,7 @@ This pattern allows us, e.g. ## Ingestion Profile {#ingestion-profile} -This ingestion profile specifies the set of 'moustache'-variables that [interpreters](@) for ingestible content is expected to populate, and pass on to the [transformer](@) that will create a copy of that ingestible content and transform it into a (syntactically) correct [curated text](@). There is a [template](docs/tev2/spec-files/ingestion.profile) file that can be used. +This ingestion profile specifies the set of 'moustache'-variables that [interpreters](@) for ingestible content is expected to populate, and pass on to the [transformer](@) that will create a copy of that ingestible content and transform it into a (syntactically) correct [curated text](@). There is a [template](docs/spec-files/ingestion.profile) file that can be used. :::info Editor's note The [transformer](@) that outputs a [curated text](@) still needs to be specified. Specifically, the specification should document what needs to be done in case a [curated text](@) exists whose `term` field matches the `term` field of the newly ingested file. Answers should be given for questions like: @@ -62,7 +62,7 @@ This template allows [interpreters](@) for ingestible content to be created, e.g | `glossaryText` | {{`glossaryText`}} | Y | | text that summarizes the meaning of the term. | | `synonyms` | {{`synonymsList`}} | n | | other words/phrases that mean the same. | | `grouptags` | {{`grouptagsList`}} | n | | comma-separated list of tags/keywords to which the term belongs. | -| `formPhrases` | {{`formPhrasesList`}} | n | | comma-separated list of [formPhrases](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2/spec-syntax/form-phrase-syntax) | +| `formPhrases` | {{`formPhrasesList`}} | n | | comma-separated list of [formPhrases](https://tno-terminology-design.github.io/tev2-specifications/docs/spec-syntax/form-phrase-syntax) | | `status` | {{`status`}} | n | `proposed` | status/phase in the lifecycle of the term. | | `created` | {{`created`}} | n | today | date when the term was first conceived/documented. | | `updated` | {{`updated`}} | n | today | date when the term was last updated. | diff --git a/docs/tev2/spec-files/21-mrg.md b/docs/spec-files/21-mrg.md similarity index 93% rename from docs/tev2/spec-files/21-mrg.md rename to docs/spec-files/21-mrg.md index 686c059721..d97548cbc8 100644 --- a/docs/tev2/spec-files/21-mrg.md +++ b/docs/spec-files/21-mrg.md @@ -18,7 +18,7 @@ The entire section on Terminology Engine v 2 (TEv2) is still under construction. As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', i.e. not yet processed.
[readers](@) will need to see through some (currently unprocessed) notational conventions. ::: -Every [scope](@) has (at least) one **Machine Readable Inventory**[^1] (that we call a **Machine Readable Glossary** or [MRG](@)), that renders the [terminology](@) of a specific [scope](@) into a specific, well-defined format that is described in this document. An [MRG](@) is meant to be used by the tools from the [toolbox](/docs/tev2/tev2-toolbox), e.g. for creating a [HRG](@), or to help resolve [TermRefs](@). A [scope](@) may have multiple [MRGs](@), each of which represents a specific version of its [terminology](@). +Every [scope](@) has (at least) one **Machine Readable Inventory**[^1] (that we call a **Machine Readable Glossary** or [MRG](@)), that renders the [terminology](@) of a specific [scope](@) into a specific, well-defined format that is described in this document. An [MRG](@) is meant to be used by the tools from the [toolbox](/docs-toolbox), e.g. for creating a [HRG](@), or to help resolve [TermRefs](@). A [scope](@) may have multiple [MRGs](@), each of which represents a specific version of its [terminology](@). [^1]: The [MRG](@) is an inventory rather than a [glossary](@), because it contains _all_ [knowledge artifacts](@) that are [curated](@) within the [scope](@): apart from [terms](@), it also include e.g., [mental models](pattern@) and [use cases](@). We choose to maintain the [term](@) "Machine Readable Glossary" ([MRG](@)), because most of us would view it - initially, at least - as a list of [terms](@) and their [definitions](@). @@ -30,8 +30,8 @@ Within this [glossarydir](@) we can generate (or import), and hence also find al **`mrg...yaml`** is the name of a file that contains an actual [MRG](@), or it is a file that links (references) such a file, where: -- **``** is the [scopetag](@) that [identifies](@) the [scope](@) in which the [MRG](@) is curated, as specified in the [SAF](@) of the [scope](@) we are in. Thus, its value must either be that of the `scopetag`-field in the [scope section](docs/tev2/spec-files/saf#terminology) of the [SAF](@), or it must be one of the values in the `scopetags`-field in the [scopes (plural) section](docs/tev2/spec-files/saf#scopes) of that [SAF](@). -- **``** is the [versiontag](@) that [identifies](@) the version of the [terminology](@) for which the [MRG](@) contains [entries](mrg-entry@). Its value must be either one of the `vsntag`-fields, or appear in one of the `alatvsntag`-fields in the [versions section](/docs/tev2/spec-files/saf#versions) of the [SAF](@). +- **``** is the [scopetag](@) that [identifies](@) the [scope](@) in which the [MRG](@) is curated, as specified in the [SAF](@) of the [scope](@) we are in. Thus, its value must either be that of the `scopetag`-field in the [scope section](docs/spec-files/saf#terminology) of the [SAF](@), or it must be one of the values in the `scopetags`-field in the [scopes (plural) section](docs/spec-files/saf#scopes) of that [SAF](@). +- **``** is the [versiontag](@) that [identifies](@) the version of the [terminology](@) for which the [MRG](@) contains [entries](mrg-entry@). Its value must be either one of the `vsntag`-fields, or appear in one of the `alatvsntag`-fields in the [versions section](/docs/spec-files/saf#versions) of the [SAF](@). This naming convention enables tools (as well as [curators](@) and others) that operate within a particular [scope](@), to quickly find a particular [MRG](@) that is relevant for that [scope](@). @@ -48,7 +48,7 @@ A Machine Readable Glossary (MRG) is a YAML (or JSON) file that has three sectio ~~~ yaml terminology: # the fields below must match the corresponding data in the SAF scopetag: tev2 # scope, the terminology of which is contained in this MRG - scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/tev2 + scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs curatedir: terms vsntag: v0.9.4 altvsntags: [ latest ] @@ -113,7 +113,7 @@ An [MRG entry](@) has a few fields that are always present, because the [MRGT](@ | -------------- | :---------- | | `scopetag` | [Scopetag](@) that [identifies](@) the [scope](@) from within which the contents of the [MRG entry](@) is [curated](@), and obtained. The [`scopes` section](#mrg-scopes) in the [MRG](@) SHOULD contain a mapping between the `scopetag` and its associated [scope directory](@).| | `locator` | path, relative to `scopedir`/`curatedir`/, where `scopedir` can be obtained from the `scopes` section of the [MRG](@), and `curatedir` can be obtained from the [SAF](@) that lives in this `scopedir`, where the [curated text](@) lives from which the contents of the [MRG entry](@) was constructed. | -| `navurl` | path, relative to the URL as specified in the `website` field in the [`scope` section](/docs/tev2/spec-files/saf#terminology) of the [SAF](@) (that lives in the `scopedir` as specified in the `scopes` section of the [MRG](@)), where the rendered version of the [curated text](@) is located. | +| `navurl` | path, relative to the URL as specified in the `website` field in the [`scope` section](/docs/spec-files/saf#terminology) of the [SAF](@) (that lives in the `scopedir` as specified in the `scopes` section of the [MRG](@)), where the rendered version of the [curated text](@) is located. | | `headingids` | a list of the [markdown headings](https://www.markdownguide.org/basic-syntax/#headings) and/or [heading ids](https://www.markdownguide.org/extended-syntax/#linking-to-heading-ids) that are found in the [curated text](@). | An [MRG entry](@) has additional fields that come from the front matter of the [curated text](@) that the [MRG entry](@) represents. Some fields are @@ -147,7 +147,7 @@ The following table documents the fields that are used within the context of [TE | `glossaryText` | n | Text that is used as the (raw) contents for the entry of this [term](@) in a human readable [glossary](@). Such texts SHOULD be allowed to contain [TermRefs](@). | | `synonymOf` | n | [term identifier](@) that [identifies](@) the defined [term](@) of the [terminological artifact](@) for which this is a [synonym](@). | | `grouptags` | n | List of [grouptags](@), each of which signifies that the [(scoped) term](@) that this [curated text](@) documents, is part of the group of [terms](@) that it represents.
Example: `[tev2, management]`.
Must satisfy regex [`(?:\[\s*([a-z0-9_-]+)\s*(?:,\s*([a-z0-9_-]+))*\s*\])?`](https://www.debuggex.com/r/a51CXl1NzR3kwihT). | -| `formPhrases` | n | List of [texts](formphrase@) that are [used to convert](/docs/tev2/spec-tools/trrt#id) the `show text` parts of [TermRefs](@) into `term`s, for the purpose of accommodating plural forms (for nouns) or conjugate forms (for verbs). For details, see ['Syntax Specs - Form Phrases](/docs/tev2/spec-syntax/form-phrase-syntax). | +| `formPhrases` | n | List of [texts](formphrase@) that are [used to convert](/docs/spec-tools/trrt#id) the `show text` parts of [TermRefs](@) into `term`s, for the purpose of accommodating plural forms (for nouns) or conjugate forms (for verbs). For details, see ['Syntax Specs - Form Phrases](/docs/spec-syntax/form-phrase-syntax). | | `status` | n | Text that identifies the status of the term. ([Communities](@) of) [scopes](@) may specify values for this field. An example is the [status tags used by ToIP](https://github.com/trustoverip/concepts-and-terminology-wg/blob/master/docs/status-tags.md). | | `created` | n | Date at which of the [curated text](@) was created, in the date format as used within this [scope](@). | | `updated` | n | Date at which of the [curated text](@) was last modified, in the date format as used within this [scope](@). | diff --git a/docs/tev2/spec-files/22-hrg.md b/docs/spec-files/22-hrg.md similarity index 89% rename from docs/tev2/spec-files/22-hrg.md rename to docs/spec-files/22-hrg.md index b95927c49e..891a461b11 100644 --- a/docs/tev2/spec-files/22-hrg.md +++ b/docs/spec-files/22-hrg.md @@ -26,7 +26,7 @@ This document specifies the contents of the [Human Readable Glossary](hrg@) file A [HRG](@) is a [glossary](@) is meant to be readable by humans, so that they can find out the meaning of [terms](@) as they are used in the context in which that [glossary](@) is valid. Thus, [HRGs](@) come in human readable formats, such as HTML or PDF. -[HRGs](@) are generated by the [HRGT](@) [tool](/docs/tev2/spec-tools/hrgt), which allows its output to be highly customized. For example, the tool expects that its user specifies +[HRGs](@) are generated by the [HRGT](@) [tool](/docs/spec-tools/hrgt), which allows its output to be highly customized. For example, the tool expects that its user specifies - the set of [terms](@) that need to be included; - the particular way in which a [term](@) (and its description) appear in the [HRGT](@) - any attributes (e.g. contributors, authors, license information etc.) need to be part of such a description, or need to be mentioned in the beginning or the end of the [HRG](@) @@ -36,8 +36,8 @@ A [HRG](@) is a [glossary](@) is meant to be readable by humans, so that they ca Within (the [glossarydir](@) of) a particular [scopedir](@), we can generate (or import) and hence find all [HRG](@)-files that are needed within that [scope](@). We use the following file naming convention: **`hrg...`** is the name of a file that contains an actual [HRG](@), or it is a file that links (references) such a file, where: - - **`.`** is taken from the [MRG](@)-file from which the [HRG](@) is generated. See [MRG file naming](/docs/tev2/spec-files/mrg#mrg-file-naming) for details. - - **``** is a text that has been provided by the user that generated the [HRG](@). It includes the file extension (e.g., PDF, HTML, etc.) that is appropriate for its contents. See [HRG generation](/docs/tev2/spec-tools/hrgt#calling-the-tool) for details. + - **`.`** is taken from the [MRG](@)-file from which the [HRG](@) is generated. See [MRG file naming](/docs/spec-files/mrg#mrg-file-naming) for details. + - **``** is a text that has been provided by the user that generated the [HRG](@). It includes the file extension (e.g., PDF, HTML, etc.) that is appropriate for its contents. See [HRG generation](/docs/spec-tools/hrgt#calling-the-tool) for details. This naming convention enables tools (as well as [curators](@) and others) that operate within a particular [scope](@), to quickly find a particular [HRG](@) that is relevant for that [scope](@). diff --git a/docs/tev2/spec-files/51-mrd.md b/docs/spec-files/51-mrd.md similarity index 100% rename from docs/tev2/spec-files/51-mrd.md rename to docs/spec-files/51-mrd.md diff --git a/docs/tev2/spec-files/52-hrd.md b/docs/spec-files/52-hrd.md similarity index 100% rename from docs/tev2/spec-files/52-hrd.md rename to docs/spec-files/52-hrd.md diff --git a/docs/tev2/spec-files/ingestion.profile b/docs/spec-files/ingestion.profile similarity index 92% rename from docs/tev2/spec-files/ingestion.profile rename to docs/spec-files/ingestion.profile index 1a885100c0..9fe6173d76 100644 --- a/docs/tev2/spec-files/ingestion.profile +++ b/docs/spec-files/ingestion.profile @@ -1,6 +1,6 @@ --- # TEv2 Curated Text Header -# Documented at: https://tno-terminology-design.github.io/tev2-specifications/docs/tev2/tev2-profile-templates#ingestion-profile +# Documented at: https://tno-terminology-design.github.io/tev2-specifications/docs-profile-templates#ingestion-profile term: {{term}} # (required) word/phrase that represents a concept. termType: {{termType}} # (optional) kind of concept (e.g. `concept` (default), or `mental model`). isa: {{isa}} # (optional) concept of which this is a specialization. @@ -8,7 +8,7 @@ glossaryTerm: glossaryText: {{glossaryText}} # (required) text that summarizes the meaning of the term. synonyms: {{commaSeparatedSynonyms}} # (optional) other words/phrases that mean the same. groupTags: {{commaSeparatedKeywords}} # (optional) list of tags/keywords to which the term belongs. -formPhrases: {{commaSeparatedFormPhrases}} # (optional) list of formPhrases (see https://tno-terminology-design.github.io/tev2-specifications/docs/tev2/spec-syntax/form-phrase-syntax) +formPhrases: {{commaSeparatedFormPhrases}} # (optional) list of formPhrases (see https://tno-terminology-design.github.io/tev2-specifications/docs/spec-syntax/form-phrase-syntax) # Curation status status: {{status}} # (optional) status/phase in the lifecycle of the term. Defaults to `proposed`. created: {{created}} # (optional) date when the term was first conceived/documented. Defaults to today's date. diff --git a/docs/tev2/spec-syntax/11-term-ref-syntax.md b/docs/spec-syntax/11-term-ref-syntax.md similarity index 95% rename from docs/tev2/spec-syntax/11-term-ref-syntax.md rename to docs/spec-syntax/11-term-ref-syntax.md index 41c7dccab9..86f86e59da 100644 --- a/docs/tev2/spec-syntax/11-term-ref-syntax.md +++ b/docs/spec-syntax/11-term-ref-syntax.md @@ -20,12 +20,12 @@ As an [author](@) or [curator](@), you want to be able to mark words or phrases, :::info Editor's note Also, you will want to (and actually can) control the effect that your [TermRefs](@) must have when it is rendered. After all, the effect you seek it to have as part of a rendered static website (e.g. so that it produces a popup with its definition) would be quite different form when it would be part of a PDF (in which case you may want it to become part of an automatically generated [glossary](@) in one of the papers annexes). Selecting the effect is done by properly instructing the [TermRef resolution tool](trrt@) when your text is processed for rendering. -We need some text here that points to the documentation for doing so. This could be e.g. in the [authors manual](/docs/tev2/manuals/author) and [curators manual](/docs/tev2/manuals/curator), but also in the [TRRT specifications](/docs/tev2/spec-tools/trrt), or in some manual that deals with adding rendering plugins. +We need some text here that points to the documentation for doing so. This could be e.g. in the [authors manual](/docs/manuals/author) and [curators manual](/docs/manuals/curator), but also in the [TRRT specifications](/docs/spec-tools/trrt), or in some manual that deals with adding rendering plugins. ::: while at the same time referring to the [definition](@) that defines its meaning. i.e. the syntax that you need to use in such texts. The way in which the [term](@) (and its [definition](@)) may be rendered depends on the artifact that is being generated. For example, when a [term](@) is rendered in a web-site, it may be enhanced, showing a popup that contains its [definition](@) when a [reader](@) hovers the mouse over it, and that hyperlinks to the page in the website that explains the term in more detail when the [reader](@) clicks on it. When a [term](@) is rendered in a PDF file, its definition may appear as an entry in a [glossary](@) that is added somewhere in the PDF. It all depends on the rendering tools that are being used, and this is out of scope for this specification. -This file specifies the syntax of [TermRefs](@). The [TRRT](@) describes [how they are processed (resolved)](/docs/tev2/spec-tools/trrt#term-ref-resolution). +This file specifies the syntax of [TermRefs](@). The [TRRT](@) describes [how they are processed (resolved)](/docs/spec-tools/trrt#term-ref-resolution). ## Term References (Original/Default Syntax) {#basic-syntax} @@ -51,7 +51,7 @@ It must not contain the characters `@` or `]` (this is needed to distinguish [Te **`term`** is the [(scoped) term](@) that [identifies](@) the [knowledge artifact](@) that is to be referred to.
It must satisfy the regex `[a-z0-9_-]+`. -If omitted, its value is assumed to be [derivable from `showtext`](/docs/tev2/spec-tools/trrt#id). +If omitted, its value is assumed to be [derivable from `showtext`](/docs/spec-tools/trrt#id). At a minimum, this is the case if the `term` equals the result of processing `showtext` by first converting every character in the range `[A-Z]` to lower-case, and then replacing every sequence of characters specified by regex `[^A-Za-z_-]+` with (a single) `-` character. ### `trait` {#trait} @@ -76,7 +76,7 @@ If omitted, a default [scope](@) will be used, which is the [scope](@) from whic If omitted (in which case the preceding `:`-character may also be omitted), its value will be the default, which is determined by the [curators](@) of that [scope](@) (the [MRG](@) that has the [terminology](@) that contains the (scoped) term](scoped-term@) that is being referenced, is specified in the [SAF](@) of that [scope](@), in the appropriate `scopes.mrgfile`-field). A `vsntag` is only valid if it appears as the value of the `vsntag` field or an element of the `altvsntags` field in one of the list-elements of the `versions` field in the [SAF](@) of the [scope](@). :::info Editor's note -It has been suggested to provide [TermRef](@) syntax that allows one to refer to a [knowledge artifact](@) from a [terminology] that was 'current'/'latest'/... at a particular date. The [SAF](@) [versioning specifications](/docs/tev2/spec-files/saf#versions) already cater for `from` and `to` dates, but everything else needs to be worked out. +It has been suggested to provide [TermRef](@) syntax that allows one to refer to a [knowledge artifact](@) from a [terminology] that was 'current'/'latest'/... at a particular date. The [SAF](@) [versioning specifications](/docs/spec-files/saf#versions) already cater for `from` and `to` dates, but everything else needs to be worked out. ::: ### Alternative notation {#alternative-syntax} diff --git a/docs/tev2/spec-syntax/21-form-phrase-syntax.md b/docs/spec-syntax/21-form-phrase-syntax.md similarity index 82% rename from docs/tev2/spec-syntax/21-form-phrase-syntax.md rename to docs/spec-syntax/21-form-phrase-syntax.md index d8f9309905..e3867ee8eb 100644 --- a/docs/tev2/spec-syntax/21-form-phrase-syntax.md +++ b/docs/spec-syntax/21-form-phrase-syntax.md @@ -19,9 +19,9 @@ This document specifies the syntax of [form phrases](@), i.e. texts that are - specified in the header field `formphrases` in [curated texts](@); - conformant to the (PCRE) regex `(?:\s*(?:[a-z0-9_-{}]+)\s*(?:,\s*([a-z0-9_-{}]+))*)?` (see [Debuggex](https://www.debuggex.com/r/20MNb2zgNwLDD-dD) for a visualization). - present in [MRG entries](@); -- [used to convert](/docs/tev2/spec-tools/trrt#id) the `show text` parts of [TermRefs](@) into `term`s, for the purpose of accommodating plural forms (for nouns) or conjugate forms (for verbs). +- [used to convert](/docs/spec-tools/trrt#id) the `show text` parts of [TermRefs](@) into `term`s, for the purpose of accommodating plural forms (for nouns) or conjugate forms (for verbs). -Note that the [syntax of `formphrases`](/docs/tev2/spec-syntax/form-phrase-syntax) enables the use use of 'macro's, i.e. shorthand syntax that represent regexes that allow for extended matching. +Note that the [syntax of `formphrases`](/docs/spec-syntax/form-phrase-syntax) enables the use use of 'macro's, i.e. shorthand syntax that represent regexes that allow for extended matching. A formphrase 'macro' is a set of characters between braces `{` and `}` that are shorthand for a matcher regex, and can be used by [authors](@) to conventiently specify a set of phrases that, when matched, would refer to the [curated text](@) in which they are specified. @@ -36,7 +36,7 @@ formPhrases: actor{ss} The part `{ss}` is a macro, that suppose it is associated with the regex `(?:'?s|\(s\))?`. -When the [trrt](@) converts a [TermRef](@), one of the things it needs to do is to [convert a so-called `show-text` into a `term`](/docs/tev2/spec-tools/trrt#term) that exists in some [curated text](@). If the `show-text` does not match the `term` of any of the [curated texts](@), the [trrt](@) will try to match it against every form phrase in every [curated text](@), including the formphrase `actor{ss}`. +When the [trrt](@) converts a [TermRef](@), one of the things it needs to do is to [convert a so-called `show-text` into a `term`](/docs/spec-tools/trrt#term) that exists in some [curated text](@). If the `show-text` does not match the `term` of any of the [curated texts](@), the [trrt](@) will try to match it against every form phrase in every [curated text](@), including the formphrase `actor{ss}`. This is done as follows: 1. all macros in the formphrase are replaced with their respective regexes, thereby transforming the formphrase into a regex itself; diff --git a/docs/tev2/spec-syntax/31-hrg-termselcrit.md b/docs/spec-syntax/31-hrg-termselcrit.md similarity index 91% rename from docs/tev2/spec-syntax/31-hrg-termselcrit.md rename to docs/spec-syntax/31-hrg-termselcrit.md index 158420de11..d87b1ef031 100644 --- a/docs/tev2/spec-syntax/31-hrg-termselcrit.md +++ b/docs/spec-syntax/31-hrg-termselcrit.md @@ -26,7 +26,7 @@ As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', When [curators](@) generate an [HRG](@) from a particular [MRG](@), they may want to specify the [terms](@) to be included in the [HRG](@) (or preventing specific [MRG entries](@) from being included). -This can be done by using the same mechanism for [terminology construction](/docs/tev2/spec-tools/terminology-construction) as is used for generating [MRGs](@). The differences are that there is only one source, i.e. the particular [MRG](@) from which the [HRG](@) is generated. Thus, references to [terms](@) that have no corresponding [MRG entry](@) in that [MRG](@) are invalid. Also, there is no need for renaming syntax. +This can be done by using the same mechanism for [terminology construction](/docs/spec-tools/terminology-construction) as is used for generating [MRGs](@). The differences are that there is only one source, i.e. the particular [MRG](@) from which the [HRG](@) is generated. Thus, references to [terms](@) that have no corresponding [MRG entry](@) in that [MRG](@) are invalid. Also, there is no need for renaming syntax. diff --git a/docs/tev2/spec-tools/11-ict.md b/docs/spec-tools/11-ict.md similarity index 94% rename from docs/tev2/spec-tools/11-ict.md rename to docs/spec-tools/11-ict.md index a2640d5b18..2034d89052 100644 --- a/docs/tev2/spec-tools/11-ict.md +++ b/docs/spec-tools/11-ict.md @@ -45,7 +45,7 @@ As the tool hasn't been made, and no practical experience has been gained, many ::: :::info Editor's Note -There's a lot of duplication in syntax specs. For example, the [SAF spec]/tev2/spec-files/saf and [MRG spec]/tev2/spec-files/mrg define the regex for various kinds of tags all over the place. It would be nice to have a way by which syntax can be specified in one location that is 'naturally predictable' so that both readers and maintainers of the documentation can easily find it. One way might be to include the syntax in a 'popover', i.e. that we define stuff with particular syntax as a [concept](@) and have the syntax be included in its `hoverText`. +There's a lot of duplication in syntax specs. For example, the [SAF spec](docs/spec-files/saf) and [MRG spec](/docs/spec-files/mrg) define the regex for various kinds of tags all over the place. It would be nice to have a way by which syntax can be specified in one location that is 'naturally predictable' so that both readers and maintainers of the documentation can easily find it. One way might be to include the syntax in a 'popover', i.e. that we define stuff with particular syntax as a [concept](@) and have the syntax be included in its `hoverText`. ::: ## Calling the Tool @@ -86,7 +86,7 @@ The columns in the following table are defined as follows: | :-- | :---- | :---: | :--: | :---------- | | `config` | `` | n | * | Path (including the filename) of the tool's (YAML) configuration file. This file contains the default key-value pairs to be used. Allowed keys (and the associated values) are documented in this table. Command-line arguments override key-value pairs specified in the configuration file. This parameter SHOULD NOT appear in the configuration file itself. | | `scopedir` | `` | Y | * | Path to the [scopedir](@) within which the tool is to operate, i.e.: _this scopedir_. | -| `syntax` | | n | * | This argument has no value. If present, the syntax of all (YAML) fields in the file is checked against their specifications (see e.g. [SAF specs]/tev2/spec-files/saf, [terminology construction](/docs/tev2/spec-tools/terminology-construction), [MRG specs]/tev2/spec-files/mrg, [Curated Texts](/docs/tev2/spec-files/ctext), [TermRefs](/docs/tev2/spec-syntax/term-ref-syntax)). | +| `syntax` | | n | * | This argument has no value. If present, the syntax of all (YAML) fields in the file is checked against their specifications (see e.g. [SAF specs](docs/spec-files/saf), [terminology construction](/docs/spec-tools/terminology-construction), [MRG specs](/docs/spec-files/mrg), [Curated Texts](/docs/spec-files/ctext), [TermRefs](/docs/spec-syntax/term-ref-syntax)). | | `vsntag` | `` | | `-mrg` | [versiontag](@) that is used to select the version of the [MRG](@) to be checked. The [MRG](@) that is selected will either have `` as the contents of the field `terminology.vsntag`, or as an element in the list of `terminology.alvsntags`. | | `term` | `` | n | -txt | [term](@) that [identifies](@) a particular [curated file](@). The [curated file](@), whose (front-matter) field `term` matches this parameter, will be integrity-checked. | | `termtypes` | `` | n | -txt | List of texts that serve to identify a specific kind of [knowledge artifact](@), e.g. `concept`, or `pattern`. Every [curated file](@), whose (front-matter) field `termtype` appears as an element in the `` list, will be integrity-checked. | diff --git a/docs/tev2/spec-tools/12-mrg-importer.md b/docs/spec-tools/12-mrg-importer.md similarity index 89% rename from docs/tev2/spec-tools/12-mrg-importer.md rename to docs/spec-tools/12-mrg-importer.md index 8a0ee9e849..e1b39f61a8 100644 --- a/docs/tev2/spec-tools/12-mrg-importer.md +++ b/docs/spec-tools/12-mrg-importer.md @@ -28,7 +28,7 @@ As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', This section is still under development. You'll see further editor's notes where issues exist. ::: -The **[MRG](@) Import Tool ([MRG importer](@))** ensures that the [scope](@) within which it is run, obtains a local copy of all [MRGs](@) that are available in the [scopes](@) that are mentioned in the [scopes section](/docs/tev2/spec-files/saf#scopes) of its [SAF](@). This makes life easy for various tools, e.g., the [MRGT](@) and the [TRRT](@), that can now assume that all [MRGs](@) that they may need to consult in order to do their job, are readily available. +The **[MRG](@) Import Tool ([MRG importer](@))** ensures that the [scope](@) within which it is run, obtains a local copy of all [MRGs](@) that are available in the [scopes](@) that are mentioned in the [scopes section](/docs/spec-files/saf#scopes) of its [SAF](@). This makes life easy for various tools, e.g., the [MRGT](@) and the [TRRT](@), that can now assume that all [MRGs](@) that they may need to consult in order to do their job, are readily available. There will shortly be an implementation of the tool: - the repo for the code of the tool is [here](https://github.com/tno-terminology-design/mrg-import). @@ -88,7 +88,7 @@ Then, the [MRG importer](@) reads the [SAF](@) of the [scope](@) from which the - `{my-own-scopedir}` = `scopedir`-field from the `scope`-section - `{my-own-glossarydir}` = `glossarydir`-field from the `scope`-section -The [MRG importer](@) also reads the [scopes section](/tev2-specifications/docs/tev2/spec-files/saf#scopes) of the [SAF](@), which specifies the 'other' [scopes](@) from which the actively maintained [MRGs](@) have to be imported. This [scopes section](/tev2-specifications/docs/tev2/spec-files/saf#scopes) contains elements that consist of two parts, whose values we will refer to by the following names: +The [MRG importer](@) also reads the [scopes section](/tev2-specifications/docs/spec-files/saf#scopes) of the [SAF](@), which specifies the 'other' [scopes](@) from which the actively maintained [MRGs](@) have to be imported. This [scopes section](/tev2-specifications/docs/spec-files/saf#scopes) contains elements that consist of two parts, whose values we will refer to by the following names: - `{import-scopetag}` = `scopetag`-field from the `scopes`-section of the [SAF](@) - `{import-scopedir}` = `scopedir`-field from the `scopes`-section of the [SAF](@) @@ -102,7 +102,7 @@ We will use: - `{other-scopetag}` = the `scopetag`-field in the `scope` section of `{import-saf}`; - `{other-glossarydir}` = the `glossarydir`-field in the `scope` section of `{import-saf}`; -The [versions-section](/tev2-specifications/docs/tev2/spec-files/saf#versions) in `{import-saf}` specifies which [terminologies](@) are actively maintained within the other [scope](@), and hence have to be imported. Every such [terminology](@) is specified by an entry in this section, and must hence be processed to import the associated [MRGs](@). +The [versions-section](/tev2-specifications/docs/spec-files/saf#versions) in `{import-saf}` specifies which [terminologies](@) are actively maintained within the other [scope](@), and hence have to be imported. Every such [terminology](@) is specified by an entry in this section, and must hence be processed to import the associated [MRGs](@). To specify one such process, we will use: - `{other-vsntag}` = `vsntag`-field in the element of the `versions` section of `{import-saf}` diff --git a/docs/tev2/spec-tools/13-trrt.md b/docs/spec-tools/13-trrt.md similarity index 90% rename from docs/tev2/spec-tools/13-trrt.md rename to docs/spec-tools/13-trrt.md index 53ed6b781e..3d7faa5a10 100644 --- a/docs/tev2/spec-tools/13-trrt.md +++ b/docs/spec-tools/13-trrt.md @@ -25,7 +25,7 @@ As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', ::: :::info Editor's note -Term ref resolution is the same process as we use for ingestion, and other conversions, as (will be) explained in the [profiles template section](/docs/tev2/spec-files/profile-templates). When that 'conversion pattern' is stable and properly documented, we need to revise this section to align with those descriptions. +Term ref resolution is the same process as we use for ingestion, and other conversions, as (will be) explained in the [profiles template section](/docs/spec-files/profile-templates). When that 'conversion pattern' is stable and properly documented, we need to revise this section to align with those descriptions. ::: The **Term Ref(erence) Resolution Tool ([TRRT](@))** takes files that contain so-called [TermRefs](@) and outputs a copy of these files in which these [TermRefs](@) are converted into so-called [renderable refs](@), i.e. texts that can be further processed by tools such as GitHub pages, Docusaurus, etc. The result of this is that the rendered document contains markups that help [readers](@) to quickly find more explanations of the [concept](@) or other [knowledge artifact](@) that is being referenced. @@ -127,7 +127,7 @@ The columns in the following table are defined as follows: | `input` | `` | n | [Globpattern](https://en.wikipedia.org/wiki/Glob_(programming)#Syntax) that specifies the set of (input) files that are to be processed. | | `output` | `

` | Y | (Root) directory where output files are to be written. This directory is specified as an absolute or relative path. | | `scopedir` | `` | Y | Path of the [scope directory](@) from which the tool is called. It MUST contain the [SAF](@) for that [scope](@), which we will refer to as the 'current scope' for the [TRRT](@). | -| `version` | `` | n | Version of the [terminology](@) that is to be used to resolve [TermRefs](@) for which neither a `scope` nor a `version` part has been specified (which is the most common case). It MUST match either the `vsntag` field, or an element of the `altvsntags` field as specified in the [`versions` section](/docs/tev2/spec-files/saf#versions) of the [SAF](@). When not specified, its value is taken from the `defaultvsn` field in the [terminology section](/docs/tev2/spec-files/mrg#mrg-terminology) of the default [MRG](@) (which is [identified](@) by the contents of the `mrgfile` field (in the [`scope` section](/docs/tev2/spec-files/saf#terminology) of the [SAF](@)). | +| `version` | `` | n | Version of the [terminology](@) that is to be used to resolve [TermRefs](@) for which neither a `scope` nor a `version` part has been specified (which is the most common case). It MUST match either the `vsntag` field, or an element of the `altvsntags` field as specified in the [`versions` section](/docs/spec-files/saf#versions) of the [SAF](@). When not specified, its value is taken from the `defaultvsn` field in the [terminology section](/docs/spec-files/mrg#mrg-terminology) of the default [MRG](@) (which is [identified](@) by the contents of the `mrgfile` field (in the [`scope` section](/docs/spec-files/saf#terminology) of the [SAF](@)). | | `interpreter` | `` | n | Allows for the switching between interpreter types. By default the `AltInterpreter` and `StandardInterpreter` are available. When this parameter is omitted, the basic [TermRef](@) syntax is used. | | `converter` | `` | n | The type of converter which creates the [renderable refs](@). When this parameter is omitted, the Markdown converter is used. | @@ -141,8 +141,8 @@ The [TermRef](@) resolution process has three steps: ### Interpretation of the Term Ref The following kinds of [TermRef](@) syntaxes are (to be) supported: -- the [basic syntax](/docs/tev2/spec-syntax/term-ref-syntax#basic-syntax), i.e. \[`show text`\](`term`#`trait`@`scopetag`:`vsntag`); -- the [alternative syntax](/docs/tev2/spec-syntax/term-ref-syntax#alternative-syntax), e.g. \[`show text`@\], which basically moves the `@`-character from the basic syntax within the square brackets, which in many (if not most) cases is more convenient for [authors](@), but has the drawback that the rendering of the plain markdown text would be rendered as [show text@], which may be inconvenient. +- the [basic syntax](/docs/spec-syntax/term-ref-syntax#basic-syntax), i.e. \[`show text`\](`term`#`trait`@`scopetag`:`vsntag`); +- the [alternative syntax](/docs/spec-syntax/term-ref-syntax#alternative-syntax), e.g. \[`show text`@\], which basically moves the `@`-character from the basic syntax within the square brackets, which in many (if not most) cases is more convenient for [authors](@), but has the drawback that the rendering of the plain markdown text would be rendered as [show text@], which may be inconvenient. Interpretation of a [TermRef](@) leads to the population of the following variables (or, in case regexes are used, named capturing groups): @@ -151,11 +151,11 @@ Interpretation of a [TermRef](@) leads to the population of the following variab Finding a [TermRef](@) in the file can be done by using a regular expressions (regexes - you can use [debuggex](https://www.debuggex.com/) to see what these regexps do (make sure you choose PCRE as the regex flavor to work with)). -- For the [basic syntax](/docs/tev2/spec-syntax/term-ref-syntax#basic-syntax), you can use the PCRE regex +- For the [basic syntax](/docs/spec-syntax/term-ref-syntax#basic-syntax), you can use the PCRE regex - [``(?:(?<=[^`\\])|^)\[(?=[^@\]]+\]\([#a-z0-9_-]*@[:a-z0-9_-]*\))``](https://www.debuggex.com/r/G1uvznpNG1mhqEx5) to find the `[` that starts a [TermRef](@), and - [``(?[^\n\]@]+)\]\((?:(?[a-z0-9_-]*)?(?:#(?[a-z0-9_-]+))?)?@(?[a-z0-9_-]*)(?::(?[a-z0-9_-]+))?\)``](https://www.debuggex.com/r/36D57uOvsnyPehh3) to find the various parts of the [TermRef](@) as (named) capturing groups. -- For the [alternative syntax](/docs/tev2/spec-syntax/term-ref-syntax#alternative-syntax), you can use the PCRE regex +- For the [alternative syntax](/docs/spec-syntax/term-ref-syntax#alternative-syntax), you can use the PCRE regex - [``(?:(?<=[^`\\])|^)\[(?=[^@\]]+@[:a-z0-9_-]*\](?:\([#a-z0-9_-]+\))?)``](https://www.debuggex.com/r/7dEYEdoc52QeIxf4) to find the `[` that starts a [TermRef](@), and - [``(?[^\n\]@]+?)@(?[a-z0-9_-]*)(?::(?[a-z0-9_-]+?))?\](?:\((?[a-z0-9_-]*)(?:#(?[a-z0-9_-]+?))?\))?``](https://www.debuggex.com/r/tMBiAk_W9ipNc9Mm) to subsequently obtain the various fields as (named) capturing groups from the PCRE regex. @@ -182,7 +182,7 @@ If not specified, the current [scope](@) (from which the [TRRT](@) is being call `vsntag` is a [versiontag](@) that [identifies](@) the version of the [terminology](@) in the [scope](@) (as [identified] by the `scopetag`). It MUST appear either in the `vsntag` field, or as one of the elements in the `altvsntags` field of the [SAF](@) that contains the administration of that [scope](@). -If omitted (in which case the preceding `:`-character may also be omitted from the syntax), its value will [identify](@) the default [MRG](@) of the [scope](@) (as [specified](/docs/tev2/spec-files/saf#terminology) in the `mrgfile` field os the [SAF](@)). +If omitted (in which case the preceding `:`-character may also be omitted from the syntax), its value will [identify](@) the default [MRG](@) of the [scope](@) (as [specified](/docs/spec-files/saf#terminology) in the `mrgfile` field os the [SAF](@)). #### `term` (optional) {#id} @@ -193,10 +193,10 @@ If omitted, it is generated as f - set `term`:=`showtext`; - convert every character in the (regex) range `[A-Z]` to lower-case; - convert every sequence of characters `[^A-Za-z_-]+` to (a single) `-` character; -- if the resulting `term` [matches an element in the list of texts](/docs/tev2/spec-syntax/form-phrase-syntax) in the `formphrases` field of an [MRG entry](@), then replace `term` with the contents of the `term`-field of that same [MRG entry](@). +- if the resulting `term` [matches an element in the list of texts](/docs/spec-syntax/form-phrase-syntax) in the `formphrases` field of an [MRG entry](@), then replace `term` with the contents of the `term`-field of that same [MRG entry](@). :::info Editor's note -We should clarify the extent to which this `matching` supports formphrase macro's, Currently, this is documented as part of the [form-phrase syntax](/docs/tev2/spec-syntax/form-phrase-syntax) which doesn't seem right. +We should clarify the extent to which this `matching` supports formphrase macro's, Currently, this is documented as part of the [form-phrase syntax](/docs/spec-syntax/form-phrase-syntax) which doesn't seem right. ::: It is an error if the resulting `term` does not [identify](@) an [MRG entry](@) in the selected [MRG](@). This may mean that the `showtext` has misspellings, the `term` field was not specified where it had to, or the list of `formphrases` in some [MRG entry](@) should have included more elements. @@ -209,15 +209,15 @@ Perhaps the [TRRT](@) may use this tool as a means for generating the `term` fie #### `trait` (optional) {#trait} -`trait` [identifies](@) a particular kind of descriptive text that is associated with the [knowledge artifact](@). If specified, it must be one of the elements in the list of headingid's as specified in [the `headingids` field](/docs/tev2/spec-files/mrg#mrg-entries) of the [MRG entry](@). If omitted, the preceding `#`-character should also be omitted. +`trait` [identifies](@) a particular kind of descriptive text that is associated with the [knowledge artifact](@). If specified, it must be one of the elements in the list of headingid's as specified in [the `headingids` field](/docs/spec-files/mrg#mrg-entries) of the [MRG entry](@). If omitted, the preceding `#`-character should also be omitted. ### Locating the identified MRG Entry As soon as the variables have been provided with a value, the [MRG](@) can be found by following a sequence of steps: -1. **get the [scopedir](@) and [SAF](@) associated with the `scope` variable of the [TermRef](@)**. If the value of the `scopetag` variable is the [scopetag](@) of the current [scope](@) (as specified when the [tool was called](#calling-the-tool)), then use the current [scopedir](@). Otherwise, look up the [scopedir](@) from the [`scopes` section](/docs/tev2/spec-files/saf#scopes) of the current [SAF](@). From the resulting [scopedir](@), read the [SAF](@) (i.e. the `saf.yaml` file in the root of the [scopedir](@)). +1. **get the [scopedir](@) and [SAF](@) associated with the `scope` variable of the [TermRef](@)**. If the value of the `scopetag` variable is the [scopetag](@) of the current [scope](@) (as specified when the [tool was called](#calling-the-tool)), then use the current [scopedir](@). Otherwise, look up the [scopedir](@) from the [`scopes` section](/docs/spec-files/saf#scopes) of the current [SAF](@). From the resulting [scopedir](@), read the [SAF](@) (i.e. the `saf.yaml` file in the root of the [scopedir](@)). -2. **get the [MRG](@) associated with the `vsntag` of the [TermRef](@)**. Search the element in the [versions section](docs/tev2/spec-files/mrg#versions) of the [SAF](@) where the `vsntag` variable is either the value of the `vsntag` field, or appears as one of the elements in the `altvsntags` field. Then, obtain the filename of the [MRG](@) from the `mrgfile` field of that element. +2. **get the [MRG](@) associated with the `vsntag` of the [TermRef](@)**. Search the element in the [versions section](docs/spec-files/mrg#versions) of the [SAF](@) where the `vsntag` variable is either the value of the `vsntag` field, or appears as one of the elements in the `altvsntags` field. Then, obtain the filename of the [MRG](@) from the `mrgfile` field of that element. 3. **identify the [MRG entry](@) associated with the `id` field of the [TermRef](@)**. Get the [MRG](@) from the location specified by the URL ``/``/`` (which are all in the context of [scope](@) as identified by the `scopetag` variable). The [MRG entry](@) will be [identified](@) by a process that starts with the set of all [entries](mrg-entry@) that exist in the selected [MRG](@), and then weeding out any non-matching [entries](mrg-entry@) by applying the following steps: - since `term` must be present, all [entries](mrg-entry@) are removed whose `term` field differs from the `term` variable; diff --git a/docs/tev2/spec-tools/20-terminology-construction.md b/docs/spec-tools/20-terminology-construction.md similarity index 94% rename from docs/tev2/spec-tools/20-terminology-construction.md rename to docs/spec-tools/20-terminology-construction.md index 529268d119..2540d6b914 100644 --- a/docs/tev2/spec-tools/20-terminology-construction.md +++ b/docs/spec-tools/20-terminology-construction.md @@ -19,7 +19,7 @@ As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', Constructing a [terminology](@) consists of specifying the set of [terms](scoped-term@) that the [terminology](@) consists of, and making sure there is an [MRG entry](@) that holds all associated (meta) data that other (e.g. third party) tools may need. In other words, it consists of constructing the set of [MRG entries](@) for the [terms](scoped-term@) of the [terminology](@). -An [MRG entry](@) contains (meta) data about (the [(scoped) term](@) that represents/[identifies](@)) a specific [knowledge artifact](@) (an illustration can be found in the [terminology support pattern](/docs/tev2/terms/patterns/pattern-terminology#formalized-model)). For constructing a [terminology](@), the following such data is relevant (as it enables one to [identify](@) (groups of) [terms](scoped-term@) that are to become part of that [terminology](@)): +An [MRG entry](@) contains (meta) data about (the [(scoped) term](@) that represents/[identifies](@)) a specific [knowledge artifact](@) (an illustration can be found in the [terminology support pattern](/docs/terms/patterns/pattern-terminology#formalized-model)). For constructing a [terminology](@), the following such data is relevant (as it enables one to [identify](@) (groups of) [terms](scoped-term@) that are to become part of that [terminology](@)): - the (preferred) [(scoped) term](@) that represents the [knowledge artifact](@), and its synonymous [terms](scoped-term@); - various [tags](@), amongst which are the [grouptags](@) that indicate the groups of [terms](scoped-term@) that the [term](scoped-term@) is a member of. @@ -30,7 +30,7 @@ The process for creating a [terminology](@) is as follows: - [removing](#syntax-remove) [MRG entries](@) from the [terminology under construction](@); - [modifying attributes](#syntax-rename) of a specific [MRG entry](@) in the [terminology under construction](@), e.g. for renaming a term that originated from another [scope](@). -[Curators](@) create and maintain the list of '[term selection criteria](@)', i.e. instructions for constructing a specific (version of a) [terminology](@). Each such (versioned) [terminology](@) has an entry in the [`versions` section](/docs/tev2/spec-files/saf#versions) of the [SAF](@) (of the designated [scope](@)), and the [term selection criteria](@) reside in the `termselcrit` field of that section. +[Curators](@) create and maintain the list of '[term selection criteria](@)', i.e. instructions for constructing a specific (version of a) [terminology](@). Each such (versioned) [terminology](@) has an entry in the [`versions` section](/docs/spec-files/saf#versions) of the [SAF](@) (of the designated [scope](@)), and the [term selection criteria](@) reside in the `termselcrit` field of that section. ## Adding MRG Entries to the [terminology under construction](@) {#syntax-add} diff --git a/docs/tev2/spec-tools/21-mrgt.md b/docs/spec-tools/21-mrgt.md similarity index 75% rename from docs/tev2/spec-tools/21-mrgt.md rename to docs/spec-tools/21-mrgt.md index 60ca88a735..8947d01a55 100644 --- a/docs/tev2/spec-tools/21-mrgt.md +++ b/docs/spec-tools/21-mrgt.md @@ -25,14 +25,14 @@ The entire section on Terminology Engine v 2 (TEv2) is still under construction. As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', i.e. not yet processed.
[readers](@) will need to see through some (currently unprocessed) notational conventions. ::: -The **Machine Readable Glossary generation Tool ([MRGT](@))** generates a Machine Readable Glossary or [MRG](@)) for (a specific version of) the [terminology](@) of a specific [scope](@) into a specific, well-defined [format](/docs/tev2/spec-files/mrg). An [MRG](@) contains so-called [MRG entries](@) for every [term](@) in its [scope](@), which represent not only [concepts](@) but also other [knowledge artifacts](@) of other kinds, such as [mental models](@) and [use cases](@). +The **Machine Readable Glossary generation Tool ([MRGT](@))** generates a Machine Readable Glossary or [MRG](@)) for (a specific version of) the [terminology](@) of a specific [scope](@) into a specific, well-defined [format](/docs/spec-files/mrg). An [MRG](@) contains so-called [MRG entries](@) for every [term](@) in its [scope](@), which represent not only [concepts](@) but also other [knowledge artifacts](@) of other kinds, such as [mental models](@) and [use cases](@). -The (newly generated) [MRG](@) is meant to be processed by the other tools in the [toolbox](/docs/tev2/tev2-toolbox), regardless of whether such tools are called from within the context of another [scope](@). As it contains every [term](@) that is used in the [scope](@), and includes all the relevant meta-data, an [MRG](@) serves as the single, authoritative source of that (version of the) [scope's](@) [terminology](@). +The (newly generated) [MRG](@) is meant to be processed by the other tools in the [toolbox](/docs-toolbox), regardless of whether such tools are called from within the context of another [scope](@). As it contains every [term](@) that is used in the [scope](@), and includes all the relevant meta-data, an [MRG](@) serves as the single, authoritative source of that (version of the) [scope's](@) [terminology](@). There is currently one (JAVA) implementation of the tool: - the repo is [here](https://github.com/trustoverip/ctwg-toolkit-mrg/) - the documentation is [here](https://github.com/trustoverip/ctwg-toolkit-mrg#readme) -- the (deprecated) specifications for this tool are [here](https://essif-lab.github.io/framework/docs/tev2/spec-tools/mrgt) +- the (deprecated) specifications for this tool are [here](https://essif-lab.github.io/framework/docs/spec-tools/mrgt) A new implementation is envisaged (but not yet available), which will be built similar to the [TRRT](@) and [MRG Importer](@). - the repo is [here](https://github.com/tno-terminology-design/mrgt). @@ -72,7 +72,7 @@ The columns in the following table are defined as follows: | :------------- | :------------ | :---: | :---------- | | `config` | `` | n | Path (including the filename) of the tool's (YAML) configuration file. This file contains the default key-value pairs to be used. Allowed keys (and the associated values) are documented in this table. Command-line arguments override key-value pairs specified in the configuration file. This parameter MUST NOT appear in the configuration file itself. | | `scopedir` | `` | Y | Path of the [scope directory](@) from which the tool is called. It MUST contain the [SAF](@) for that [scope](@), which we will refer to as the 'current scope' for the [MRG importer](@). | -| `vsntag` | `` | n | [versiontag](@) for which the [MRG](@) needs to be (re)generated. When omitted, an [MRG](@) will be generated for every version of the [terminology](@) that is specified in the [versions section](/docs/tev2/spec-files/saf#versions) of the [SAF](@) | +| `vsntag` | `` | n | [versiontag](@) for which the [MRG](@) needs to be (re)generated. When omitted, an [MRG](@) will be generated for every version of the [terminology](@) that is specified in the [versions section](/docs/spec-files/saf#versions) of the [SAF](@) | | `onNotExist` | `` | n | specifies the action to take in case a `vsntag` was specified, but wasn't found in the [SAF](@). Default is `'throw'`. | The `` parameter can take the following values: @@ -87,43 +87,43 @@ The `` parameter can take the following values: ## Generating an MRG -The [MRGT](@) starts by reading the [SAF](@) that exists in the [scopedir](@) that was provided as one of the calling parameters. If a `vsntag` argument is provided, it will search the [versions section](/docs/tev2/spec-files/saf#versions) of the [SAF](@) to find the corresponding entry. This corresponding entry will have the value of the `vsntag` parameter either in its `vsntag` field, or it is one of the elements in the `altvsntags` field. If the [SAF](@) does not have a corresponding entry, the action specified in the `onNotExist` parameter will determine whether or not (and how) to proceed. +The [MRGT](@) starts by reading the [SAF](@) that exists in the [scopedir](@) that was provided as one of the calling parameters. If a `vsntag` argument is provided, it will search the [versions section](/docs/spec-files/saf#versions) of the [SAF](@) to find the corresponding entry. This corresponding entry will have the value of the `vsntag` parameter either in its `vsntag` field, or it is one of the elements in the `altvsntags` field. If the [SAF](@) does not have a corresponding entry, the action specified in the `onNotExist` parameter will determine whether or not (and how) to proceed. -The corresponding entry in the [SAF](@) specifies (a specific version of) a [terminology](@). It not only includes meta-data for that [terminology](@), but also the set of '[term selection criteria](@)' that specify how the [terminology](@) needs to be [constructed](/docs/tev2/spec-tools/terminology-construction), and the file to which the result needs to be written. +The corresponding entry in the [SAF](@) specifies (a specific version of) a [terminology](@). It not only includes meta-data for that [terminology](@), but also the set of '[term selection criteria](@)' that specify how the [terminology](@) needs to be [constructed](/docs/spec-tools/terminology-construction), and the file to which the result needs to be written. The [MRG](@) is then created as follows (starting with an empty file): -1. The [MRG](@) `terminology` section is created, by copying [relevant fields](/docs/tev2/spec-files/mrg#mrg-terminology) from the `terminology` section in the [SAF](@). -2. Then, [terminology construction](/docs/tev2/spec-tools/terminology-construction) takes place, which can be thought of as constructing a set of tuples `{ [term, grouptags] }`, where `term` [identifies](@) (the [curated text](@) that documents) the particular [knowledge artifact](@), and `grouptags` is a set of [grouptags](@) associated with that tuple. +1. The [MRG](@) `terminology` section is created, by copying [relevant fields](/docs/spec-files/mrg#mrg-terminology) from the `terminology` section in the [SAF](@). +2. Then, [terminology construction](/docs/spec-tools/terminology-construction) takes place, which can be thought of as constructing a set of tuples `{ [term, grouptags] }`, where `term` [identifies](@) (the [curated text](@) that documents) the particular [knowledge artifact](@), and `grouptags` is a set of [grouptags](@) associated with that tuple. 3. For every tuple in this set, an [MRG entry](@) is created, and added to the [MRG](@) under construction. The structure of each such [entry](mrg-entry@) depends on the type of the [knowledge artifact](@) that the [term](@) represents, as the [header](@) of a [curated text](@) depends on that type. After the [MRG](@) has been created, it is written to the file `mrg...yaml`, where: -- `` is the [scopetag](@) that is used within the [scope](@) to refer to itself. Its value can be found in the `scopetag`-field in the [scope section](docs/tev2/spec-files/saf#terminology) of the [SAF](@). -- `` is the [versiontag](@) that [identifies](@) the version of the [terminology](@) for which the [MRG](@) contains [entries](mrg-entry@). Its value must be equal to that found in the `vsntag`-field of the element in the [versions section](/docs/tev2/spec-files/saf#versions) of the [SAF](@) from which the [MRG](@) was generated. NOTE that [versiontags](@) that are listed in the `altvsntags`-field of such an element MUST NOT be used in the [MRG](@)-filename. +- `` is the [scopetag](@) that is used within the [scope](@) to refer to itself. Its value can be found in the `scopetag`-field in the [scope section](docs/spec-files/saf#terminology) of the [SAF](@). +- `` is the [versiontag](@) that [identifies](@) the version of the [terminology](@) for which the [MRG](@) contains [entries](mrg-entry@). Its value must be equal to that found in the `vsntag`-field of the element in the [versions section](/docs/spec-files/saf#versions) of the [SAF](@) from which the [MRG](@) was generated. NOTE that [versiontags](@) that are listed in the `altvsntags`-field of such an element MUST NOT be used in the [MRG](@)-filename. The [MRG](@) file must be written to the [glossarydir](@) of the [scope](@), which is located at `/`, where - `` is the home-directory of the [scope](@), and -- `` is the path to the directorty where all [glossary](@)-related files are located. Its value can be found in the [scope section](/docs/tev2/spec-files/saf#terminology) of the [SAF](@). +- `` is the path to the directorty where all [glossary](@)-related files are located. Its value can be found in the [scope section](/docs/spec-files/saf#terminology) of the [SAF](@). -After the [MRG](@) file has been written, the [MRGT](@) will create, a [symbolic link](https://en.wikipedia.org/wiki/Symbolic_link) for every [versiontag](@) that it finds in the `altvsntags`-field of the element in the [versions section](/docs/tev2/spec-files/saf#versions) of the [SAF](@) from which the [MRG](@) was generated. The symbolic link will point to the file that has just been written and contains the [MRG](@) that has just been generated. The name of this symbolic link is `mrg...yaml`, which is the same name as the [MRG](@) file, except that the `` part of that filename is replaced with the value of the [versiontag](@) found in the `altvsntags`-field. +After the [MRG](@) file has been written, the [MRGT](@) will create, a [symbolic link](https://en.wikipedia.org/wiki/Symbolic_link) for every [versiontag](@) that it finds in the `altvsntags`-field of the element in the [versions section](/docs/spec-files/saf#versions) of the [SAF](@) from which the [MRG](@) was generated. The symbolic link will point to the file that has just been written and contains the [MRG](@) that has just been generated. The name of this symbolic link is `mrg...yaml`, which is the same name as the [MRG](@) file, except that the `` part of that filename is replaced with the value of the [versiontag](@) found in the `altvsntags`-field. ### Creating an MRG Entry An [MRG entry](@) is either - a copy of an (existing) [MRG entry](@) that is found in an [MRG](@) that lives in another [scope](@), or -- it is constructed from a [curated text](@), which lives in a file in (one of the subdirectories of) the [curatedir](@) of the current [scope](@), as [specified](/docs/tev2/spec-files/saf#terminology) in the `curatedir` field of the [SAF](@). +- it is constructed from a [curated text](@), which lives in a file in (one of the subdirectories of) the [curatedir](@) of the current [scope](@), as [specified](/docs/spec-files/saf#terminology) in the `curatedir` field of the [SAF](@). #### Copying an MRG Entry from an existing MRG :::info -A prerequisite for generating an [MRG](@) that includes [MRG entries](@) from [MRGs](@) that are maintained in other [scopes](@), is that such other [MRGs](@) must be available in the [glossarydir](@) of the [scope](@) within which the [MRGT](@) is run. This can be achieved by running the [MRG importer](@) [tool](/docs/tev2/spec-tools/mrg-importer). If the [MRG](@) that is to be generated doesn't include such [MRG entries](@), the [MRG importer](@) need not be invoked. +A prerequisite for generating an [MRG](@) that includes [MRG entries](@) from [MRGs](@) that are maintained in other [scopes](@), is that such other [MRGs](@) must be available in the [glossarydir](@) of the [scope](@) within which the [MRGT](@) is run. This can be achieved by running the [MRG importer](@) [tool](/docs/spec-tools/mrg-importer). If the [MRG](@) that is to be generated doesn't include such [MRG entries](@), the [MRG importer](@) need not be invoked. ::: :::info Editor's note this section needs to be reviewed/revisded to ensure it fits with the [MRG importer](@) specs. ::: -In case the [MRG entry](@) is a copy, the `vsntag` [field](/docs/tev2/spec-files/mrg#mrg-entries) of that [MRG entry](@) should be given the value of the `vsntag` field that is found in the ['terminology' section](/docs/tev2/spec-files/mrg#mrg-terminology) of the [MRG](@) from which [MRG entry](@) contents was copied. +In case the [MRG entry](@) is a copy, the `vsntag` [field](/docs/spec-files/mrg#mrg-entries) of that [MRG entry](@) should be given the value of the `vsntag` field that is found in the ['terminology' section](/docs/spec-files/mrg#mrg-terminology) of the [MRG](@) from which [MRG entry](@) contents was copied. #### Constructing an MRG Entry from a Curated Text @@ -141,7 +141,7 @@ Constructing an [MRG entry](@) from a [curated text](@) is done as follows: | -------------- | :---------- | | `scopetag` | overwrite the `scopetag` field with the `scopetag` field as found in the `scope` section of the [SAF](@). | | `locator` | path, relative to `scopedir`/`curatedir`/, of the [curated text](@). | -| `navurl` | path, relative to the URL as specified in the `website` field in the [`scope` section](/docs/tev2/spec-files/saf#terminology) of the [SAF](@), where the rendered version of the [curated text](@) is located. | +| `navurl` | path, relative to the URL as specified in the `website` field in the [`scope` section](/docs/spec-files/saf#terminology) of the [SAF](@), where the rendered version of the [curated text](@) is located. | | `headingids` | a list of the [markdown headings](https://www.markdownguide.org/basic-syntax/#headings) and/or [heading ids](https://www.markdownguide.org/extended-syntax/#linking-to-heading-ids) that are found in the [curated text](@). | ## Exceptions, Warnings, and Logging {#exceptions} diff --git a/docs/tev2/spec-tools/22-hrgt-old.md b/docs/spec-tools/22-hrgt-old.md similarity index 98% rename from docs/tev2/spec-tools/22-hrgt-old.md rename to docs/spec-tools/22-hrgt-old.md index 4b1c3d0b63..7403b4ef78 100644 --- a/docs/tev2/spec-tools/22-hrgt-old.md +++ b/docs/spec-tools/22-hrgt-old.md @@ -26,7 +26,7 @@ The entire section on Terminology Engine v 2 (TEv2) is still under construction. As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', i.e. not yet processed.
[readers](@) will need to see through some (currently unprocessed) notational conventions. ::: -The **Human Readable Glossary generation Tool ([HRGT](@))** generates a Human Readable [Glossary](@) ([HRG](@)), that renders (a selection of the [terms](@) of) the [terminology](@) of a specific [scope](@) into one of several formats, e.g. HTML, or PDF. This rendering may be subject to further processing by third-party rendering tools, such as [github pages](https://pages.github.com/) or [Docusaurus](https://docusaurus.io/docs/docs-introduction), etc. (see also: [Using the Tools](/docs/tev2/tev2-toolbox)). +The **Human Readable Glossary generation Tool ([HRGT](@))** generates a Human Readable [Glossary](@) ([HRG](@)), that renders (a selection of the [terms](@) of) the [terminology](@) of a specific [scope](@) into one of several formats, e.g. HTML, or PDF. This rendering may be subject to further processing by third-party rendering tools, such as [github pages](https://pages.github.com/) or [Docusaurus](https://docusaurus.io/docs/docs-introduction), etc. (see also: [Using the Tools](/docs/tev2-toolbox)). :::info Editor's note The envisaged versatility of the [HRGT](@) is likely to imply requirements regarding, e.g.: diff --git a/docs/tev2/spec-tools/22-hrgt.md b/docs/spec-tools/22-hrgt.md similarity index 93% rename from docs/tev2/spec-tools/22-hrgt.md rename to docs/spec-tools/22-hrgt.md index 32c10dcfb1..447b315f3e 100644 --- a/docs/tev2/spec-tools/22-hrgt.md +++ b/docs/spec-tools/22-hrgt.md @@ -27,9 +27,9 @@ As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', The **Human Readable Glossary generation Tool ([HRGT](@))** generates a Human Readable [Glossary](@) ([HRG](@)) that consists of (a selection of) the [terms](@) that are part of the [terminology](@) of a specific [scope](@). -The [HRGT](@) takes one specific [MRG](@) as its input, and converts (a selection of) its [MRG entries](@) into one of the supported output formats, e.g. HTML, or PDF. The file that contains the [MRG](@) is named `mrg...yaml`, where the combination of `` and `` identify a particular [terminology](@). See the [MRG file naming conventions](/docs/tev2/spec-files/mrg#mrg-file-naming) for details. +The [HRGT](@) takes one specific [MRG](@) as its input, and converts (a selection of) its [MRG entries](@) into one of the supported output formats, e.g. HTML, or PDF. The file that contains the [MRG](@) is named `mrg...yaml`, where the combination of `` and `` identify a particular [terminology](@). See the [MRG file naming conventions](/docs/spec-files/mrg#mrg-file-naming) for details. -The selection of the [MRG entries](@) that are to be included in the [HRG](@), as well as the specification of the output format, headers, footers, etc., can be configured as well as customized. Thus, the [HRGT](@) provides a flexible means for creating all sorts of outputs that are either already human readable or can be processed further by third-party rendering tools, such as [github pages](https://pages.github.com/) or [Docusaurus](https://docusaurus.io/docs/docs-introduction), etc. (see also: [Using the Tools](/docs/tev2/tev2-toolbox)). +The selection of the [MRG entries](@) that are to be included in the [HRG](@), as well as the specification of the output format, headers, footers, etc., can be configured as well as customized. Thus, the [HRGT](@) provides a flexible means for creating all sorts of outputs that are either already human readable or can be processed further by third-party rendering tools, such as [github pages](https://pages.github.com/) or [Docusaurus](https://docusaurus.io/docs/docs-introduction), etc. (see also: [Using the Tools](/docs/tev2-toolbox)). There is currently one implementation of the tool underway: - the repo in which the tool is being developed is [tbd]. @@ -64,7 +64,7 @@ The columns in the following table are defined as follows: | `scopedir` | n | Path of the [scope directory](@) from which the tool is called. It MUST contain the [SAF](@) for that [scope](@), which we will refer to as the 'current scope' for the [HRGT](@). If omitted, the current directory is assumed to tbe the [scope directory](@). | | `input` | n | [Globpattern](https://en.wikipedia.org/wiki/Glob_(programming)#Syntax) that specifies the set of (input) files ([MRGs](@)) that are to be processed. If omitted, the [HRG](@) is generated for the default [MRG](@) of the current scope (as specified in the `mrgfile` field of the `scope` section in its [SAF](@). | | `output` | n | text that is used as the last part of the name of the file(s) that contain(s) the generated [HRG(s)](@). This text must specify an appropriate extension, such as HTML or PDF. The filename(s) will be of the form `hrg...`, where `` is the [scopetag](@) of the [scope](@) within which the [HRG](@) is generated, and `` [identifies](@) the version of the [terminology](@) in that [scope](@). From this, it follows that an [MRG](@)-file exists named `mrg...yaml`, which is used as the source for the entries in the [HRG](@). | -| `termselcrit` | n | List of [term selection criteria](@) that are used to generate (this version of) the [scope's](@) [terminology](@). If omitted, all [MRG entries](@) from the source [MRG](@) will be selected. See [Terminology Construction](/docs/tev2/spec-tools/terminology-construction) for details. | +| `termselcrit` | n | List of [term selection criteria](@) that are used to generate (this version of) the [scope's](@) [terminology](@). If omitted, all [MRG entries](@) from the source [MRG](@) will be selected. See [Terminology Construction](/docs/spec-tools/terminology-construction) for details. | | `method` | n | Text, the syntax and semantics of which remain to be specified (see also the Editor's note below). When this parameter is omitted, the [HRG](@) is generated as an HTML file. | | `license` | n | File that contains the (default) licensing conditions. Full URL is `scopedir`/`license`. If not specified, its value defaults to the value of the `license` field in the `scope` section (of the [SAF](@) of the current scope). The purpose of this field is to enable different [HRGs](@) to have different licenses. | @@ -89,11 +89,11 @@ The [HRGT](@) starts by reading its command-line and configuration file. If the Then, the [HRGT](@) reads the specified input files (in arbitrary order), and processes each of them, as follows: - select the actual [MRG](@) that is to be used as an input; -- select the (subset of) [MRG entries](@) from that [MRG](@) that must appear in the [HRG](@) - see [HRG Term Selection](/docs/tev2/spec-syntax/hrg-termselcrit) for details. Conceptually, this will result in an [MRG](@) that only contains [MRG entries](@) that need to appear in the [HRG](@) as well; +- select the (subset of) [MRG entries](@) from that [MRG](@) that must appear in the [HRG](@) - see [HRG Term Selection](/docs/spec-syntax/hrg-termselcrit) for details. Conceptually, this will result in an [MRG](@) that only contains [MRG entries](@) that need to appear in the [HRG](@) as well; - (alphabetically) sort these entries; - convert each entry into a specific 'rendered' format (as specified by the user), thereby resolving any [TermRefs](@) (by appropriately calling the [TRRT](@))[^1], adding hyperlinks to the [curated text](@) that the entry relates to, 'meta-data' (e.g. the associated [grouptags](@), contributors, etc.), and anything else, as required for the particular kind of [HRG](@) that is being generated; :::info Editor's note -The [TRRT](https://github.com/tno-terminology-design/trrt) has a nice setup for implementing [text conversion steps](/docs/tev2/overview/tev2-design-principles#text-conversion-steps). We should check that out and adapt the specifications text in this section so that this stuff can be reused as much as possible. +The [TRRT](https://github.com/tno-terminology-design/trrt) has a nice setup for implementing [text conversion steps](/docs/overview/tev2-design-principles#text-conversion-steps). We should check that out and adapt the specifications text in this section so that this stuff can be reused as much as possible. ::: - construct the [HRG](@) by adding (rendered) header- and footer-material and (optionally) licensing information; - write the [HRG](@) to the designated output file. diff --git a/docs/tev2/spec-tools/31-mrdt.md b/docs/spec-tools/31-mrdt.md similarity index 82% rename from docs/tev2/spec-tools/31-mrdt.md rename to docs/spec-tools/31-mrdt.md index f5c3f7411c..87439b24bf 100644 --- a/docs/tev2/spec-tools/31-mrdt.md +++ b/docs/spec-tools/31-mrdt.md @@ -21,9 +21,9 @@ The entire section on Terminology Engine v 2 (TEv2) is still under construction. As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', i.e. not yet processed.
[readers](@) will need to see through some (currently unprocessed) notational conventions. ::: -The **Machine Readable Dictionary generation Tool ([MRDT](@))** generates a Machine Readable Inventory (that we call a Machine Readable Dictionary or [MRD](@)) of [terms](@) that originate from different (versions of) [terminologies](@), from various [scopes](@). The inventory has a specific, well-defined [format](/docs/tev2/spec-files/mrd). Like [MRGs](@), the contents of [MRDs](@) is determined by a list of [term selection criteria](@), which specify the (sets of) terms that are to be included. +The **Machine Readable Dictionary generation Tool ([MRDT](@))** generates a Machine Readable Inventory (that we call a Machine Readable Dictionary or [MRD](@)) of [terms](@) that originate from different (versions of) [terminologies](@), from various [scopes](@). The inventory has a specific, well-defined [format](/docs/spec-files/mrd). Like [MRGs](@), the contents of [MRDs](@) is determined by a list of [term selection criteria](@), which specify the (sets of) terms that are to be included. -[MRDs](@) are meant to be processed by the other tools in the [toolbox](/docs/tev2/tev2-toolbox), specifically by one of the [HRDTs](@), which would then create a [Human Readable Dictionary](@) (or [HRD](@)). +[MRDs](@) are meant to be processed by the other tools in the [toolbox](/docs/tev2-toolbox), specifically by one of the [HRDTs](@), which would then create a [Human Readable Dictionary](@) (or [HRD](@)). [MRDs](@) can typically used to enable the creation of [HRDs](@) that are fit for specific purposes, e.g. for comparing [terminologies](@) between different [scopes](@), which helps e.g. when aligning [terminologies](@) between them. Also they can be used to provide an overview of what various [scopes](@) utilize specific terms for (education). And there's certainly going to be more such purposes. diff --git a/docs/tev2/spec-tools/32-hrdt.md b/docs/spec-tools/32-hrdt.md similarity index 97% rename from docs/tev2/spec-tools/32-hrdt.md rename to docs/spec-tools/32-hrdt.md index f019bfa248..ae313d37ad 100644 --- a/docs/tev2/spec-tools/32-hrdt.md +++ b/docs/spec-tools/32-hrdt.md @@ -26,7 +26,7 @@ The entire section on Terminology Engine v 2 (TEv2) is still under construction. As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', i.e. not yet processed.
[readers](@) will need to see through some (currently unprocessed) notational conventions. ::: -The **Human Readable Dictionary generation Tool ([HRDT](@))** generates a Human Readable [Dictionary](@) ([HRD](@)), that renders the [terms](@) from a [machine readable dictionary (MRD)](mrd@) into one of several formats, e.g. HTML, or PDF. This rendering may be subject to further processing by third-party rendering tools, such as [github pages](https://pages.github.com/) or [Docusaurus](https://docusaurus.io/docs/docs-introduction), etc. (see also: [Using the Tools](/docs/tev2/tev2-toolbox)). +The **Human Readable Dictionary generation Tool ([HRDT](@))** generates a Human Readable [Dictionary](@) ([HRD](@)), that renders the [terms](@) from a [machine readable dictionary (MRD)](mrd@) into one of several formats, e.g. HTML, or PDF. This rendering may be subject to further processing by third-party rendering tools, such as [github pages](https://pages.github.com/) or [Docusaurus](https://docusaurus.io/docs/docs-introduction), etc. (see also: [Using the Tools](/docs/tev2-toolbox)). [HRDs](@) can be created for different purposes, e.g. to - compare [terminologies](@) between different [scopes](@), which helps e.g. when aligning [terminologies](@) between them. diff --git a/docs/terminology-design/backgrounds/expressing-oneself.md b/docs/terminology-design/backgrounds/expressing-oneself.md deleted file mode 100644 index 70029cbe30..0000000000 --- a/docs/terminology-design/backgrounds/expressing-oneself.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -id: expressing-oneself -// hide_table_of_contents: true -// displayed_sidebar: terminologyDesignSideBar -date: 20221120 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -# Expressing Oneself - -This page is under construction - -A person that is called a [domain expert](@) or [subject matter expert](@) is expected to have expert knowledge on a certain (set of related) topic(s). \ No newline at end of file diff --git a/docs/terminology-design/backlog.md b/docs/terminology-design/backlog.md deleted file mode 100644 index 40a4676c6b..0000000000 --- a/docs/terminology-design/backlog.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -id: backlog -hide_table_of_contents: true -// displayed_sidebar: terminologyDesignSideBar -date: 20221020 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' -export const mark = ({children}) => ( - - {children} - ); - -# Terminology Design - Backlog/Work-in-Progress - -This page is under construction

- -This backlog of Terminology Design is a list of issues (concerns, topics) that still need to be addressed in the Terminology Design Documentation. - - -1. We may want to look into the relation of this method and 'design thinking' (see e.g. Liedtka, '[Why Design Thinking Works](https://hbr.org/2018/09/why-design-thinking-works)', Harvard Business Review, September-October 2018). diff --git a/docs/terminology-design/manuals/authoring.md b/docs/terminology-design/manuals/authoring.md deleted file mode 100644 index 124151d0a2..0000000000 --- a/docs/terminology-design/manuals/authoring.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -id: authoring -sidebar_label: Authoring -displayed_sidebar: terminologyDesignSideBar -scopetag: termdsn -date: 20230111 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -# Authoring High Quality Texts - -This page is under construction

- -:::caution -The entire section on Terminology Design is still under construction. -::: - -Every text that is written is meant to be read by people (that belong to its intended audience), and stimulate or enable them to do particular things. Whitepapers, opinion papers, specifications, standardization texts, advertisements, memo's, mails, etc. could just as well not have been written if they did not have that property. - -For us, a high-quality text is a text that not only has a specific audience and serves one or more specific purposes, but also a text that doesn't require its readers to 'hallucinate', i.e. make assumptions so as to understand the intention of its author. Such texts are typically well-suited for specifications, standards, educational materials etc. However, there are also situations in which this kind of quality is not necessary (e.g., in management summaries, or casual notes), or even counter-productive (e.g., in advertisements). - -In order to write a high-quality text, its [author(s)](@) not only need the appropriate knowledge about the topic of the text; they must have (or create) a conscious understanding of that knowledge that enables them to describe what they mean to say using [words and phrases](term@) that have a sufficiently well-defined meaning. This is not trivial: often, people that have knowledge about some topic can demonstrate that they do (using the knowledge), while not being capable of expressing the knowledge itself in a fashion that enables [readers](@) to learn it.[^1] Also, it takes discipline to (re)write texts so that in the end, all important [terms](@) are used in the way they are defined, and are used consistently and coherently. - -[^1]: For example, people that are native speakers of a language, can usually demonstrate their knowledge of the specifications of that language (its grammar), by showing that they can (1) determine whether or not a sentence in that language is grammatically correct, (2) correct the sentences that were incorrect and (3) come up with (say) 5 alternatives for correcting an incorrect sentence, and picking out 'the most beautiful', or 'the best' one. However, when asked whether they could write down the specifications such that the result is consistent, coherent, complete, cogent, congruent - and other c-words that refer to characteristics that specifications are typically expected to have, they will say 'no'. Even worse: if they are presented a booklet that is about the grammar of their mother's tongue, and are asked to determine whether or not it specifies that grammar in a consistent, coherent, complete, etc. way, they will also decline. - -This page intends to provide guidance for an [author](@) regarding how to deal with the [terminology](@) as (s)he writes a high-quality text.[^2] We assume the [author](@) has identified the audience that the text addresses, and what the audience will be doing with (the messages contained in) the text. We also assume that the [author](@) has some idea about which [terms](@) have a high likelihood of being misunderstood by (parts of) the audience, e.g. because they are contentious or can be interpreted in different ways. - -[^2]: Writing styles, methods for creating a text outline and similar topics that may be relevant for writing good texts are outside the scope. - -## Prerequisites - -:::info Editor's note -This section introduces the [scope](@) in which the text will be created. It postulates the existence of -- a glossary that contains all [terms](@) the [definition](@) (and further explanations) of which are expected to be beneficial to (some of) the [readers](@). -- a mechanism for creating and updating (parts of) such a glossary in case it doesn't exist, or needs maintenance. -::: - -## Using TermRefs - -:::info Editor's note -This section introduces [TermRefs](@), and encourages authors to use one for every occurrence of a [term](@) whose likelihood of being misunderstood by (parts of) the audience needs to be decreased. This section has some subsections -- in case the [term](@) to be used is defined in a glossary of another [scope](@) (regardless of whether or not it is defined in one's own glossary) -- in case the [term](@) to be used is not yet defined; then, a contribution to add the term must be initiated -::: - -## Creating and/or Modifying Terms - -:::info Editor's note -This section specifies how a contribution to the existing [terminology](@) of a [scope](@) can be made in the case where the [term](@): -- already exists, but has a different meaning from what the author needs; -- does not yet exist, and is relatively simple to add; -- does not yet exist, but it is not simple to add because it relies on several other terms that are not defined (in the meaning needed) -::: - -## Proofreading - -:::info Editor's note -This section specifies how to finish up the paper, by making sure that -- every [term](@) (better: [TermRef](@)) is associated with a good [definition](@); -- every [term](@) is used in the meaning in which it is defined; -::: - -## Publication - -:::info Editor's note -This section specifies what needs to be done to make it ready for publication, which consists of -- determining whether or not, and if so, where and how, a glossary needs to be made part of the paper, where that glossary contains an appropriate rendering of all [terms](@) for which a [TermRef](@) exists in the paper; -- making sure all contributions to [terms](@) that the author has made, have been properly [curated](@), and can be published with the text. -::: diff --git a/docs/terminology-design/manuals/contributing.md b/docs/terminology-design/manuals/contributing.md deleted file mode 100644 index 4c7196f04f..0000000000 --- a/docs/terminology-design/manuals/contributing.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -id: contributing -sidebar_label: Contributing -displayed_sidebar: terminologyDesignSideBar -scopetag: termdsn -date: 20230111 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -# Contributing to High Quality Texts - -This page is under construction

- -:::caution -The entire section on Terminology Design is still under construction. -::: diff --git a/docs/terminology-design/manuals/curating.md b/docs/terminology-design/manuals/curating.md deleted file mode 100644 index 9402394936..0000000000 --- a/docs/terminology-design/manuals/curating.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -id: curating -sidebar_label: Curating -displayed_sidebar: terminologyDesignSideBar -scopetag: termdsn -date: 20230111 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -# Curating High Quality Texts - -This page is under construction

- -:::caution -The entire section on Terminology Design is still under construction. -::: diff --git a/docs/terminology-design/methods.md b/docs/terminology-design/methods.md deleted file mode 100644 index 55129ba133..0000000000 --- a/docs/terminology-design/methods.md +++ /dev/null @@ -1,73 +0,0 @@ ---- -id: methods -// hide_table_of_contents: true -// displayed_sidebar: terminologyDesignSideBar -date: 20221129 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' -export const mark = ({text}) => ( {text} ); - -# Methods - -This page is under construction - -## Summary -The (high-level) process that we call **Terminology Design** aims to establish and maintain [terminologies](@) for various [contexts](@) that are suitable for, e.g.: -- creating and maintaining e.g.,: - - a common understanding between a group of people that work together as they pursue specific objectives; - - a set of (simple) documents that describe the various [terms](@), how they relate to one another (to form [mental models](@)). -- authoring well-formed arguments, nicely readable whitepapers, explanations, reference documentation, that use the [terms](@) in a consistent and coherent way, and that can readily be understood by the intended audiences of such texts. - -The key characteristic of a [terminology](@) that is designed for a particular [context](@) is that it is fit for the purpose(s) that are pursued within that [context](@). If, for example, the purpose pursued in a [context](@) is the architecture and design of IT, the [terminology](@) will be much more precise than when it were developed for a [context](@) in which coming the purpose is to come to grips with e.g., societal or ethical issues (which are inherently less precise). - -To reap the full benefits of a (well-designed) [terminology](@), a few principles must be adhered to: -1. the respective [definitions](@) of the [terms](@) that are being created and maintained in a particular [terminology](@) are to be created by the means provided by the processes we define. This basically means that the focus lies on the **MEANINGs** (distinctions) that are needed in the [context](@) for which the [terms](@) are defined, rather than on the [terms](@) that represent such meanings. -2. when doing work (e.g. making documents, discussing things, etc.) within a [context](@) for which a [terminology](@) is being maintained, the participants are committed to use the [terms](@) that are contained in that [terminology](@) in the meaning in which they are [defined](@) there (the meaning of other [terms](@) would be 'as usual'). A lack of this commitment is a counterindicator for maintaining a [terminology](@). - -The terminology design process is supported by [terminology tools](@) that enable people to document the results of this process, and use them to write other documents e.g. as part of a website, or a pdf file, or other rendered format. - -## Triggers and Counterindicators - -There are many signals that may serve as a trigger to start this process, such as: - -- the determination, by a group of people that pursues one or more [objectives](@), that they are spending (too much) time discussing topics or [terms](@) without reaching a conclusion that is satisfactory for use by every member of the group (which means that such discussions keep popping up, even if a decision has been made that should have closed it). -- the desire that is felt by all(most all) members of a group to develop a [mental model](@) on some topic. -- the felt need for creating and/or maintaining some kind of standard or other reference text. -- the need for creating some kind of framework or other foundational (set of) document(s) that are expected to serve as a basis for others to work from. - -There are also various counterindicators, i.e. signals that should prevent the process from being started, such as: - -- the participants have an insufficient interest and/or motivation to spend the time and effort to realize the intended result. -- the participants have no intention of consequently using the results in - -## Activities - -Running the process consists of executing the following activities:[^1] - -[^1]: The crucial arguments that come up during the discussions in any of these steps should be logged, so that they can be documented later and as such provide guidance to readers for understanding why certain terms are used, and certain design decisions have been made. - -1. Determine the [scope](@) of the [terminology](@) (i.e.: the [context](@) in which the [terms](@) of the [terminology](@) will be used). - -2. Determine the distinctions that participants make, and that they find relevant for realizing the [objectives](@) that they pursue within this [scope](@); use the [criteria-elicitation process](@) to ensure that all participants are enabled to make the same distinctions. - -3. Establish the set of elicited criteria that relate to one another in a way that is useful/relevant for realizing the [objectives](@), and associate a [term](@) with each of them (thereby creating a [definition](@) for that [term](@)). - -4. Use the [terms](@) in texts in the meaning as [defined](@). - -5. Whenever a use-case/text emerges that calls for the revision of one or more [terms](@), then: - 1. remove the problematic [terms](@) from the [terminology](@); - 2. re-assess the distinctions as mentioned in steps 2 and 3; - 3. repeat steps i and ii until the problem that caused the revision is resolved; - 4. revise all texts that exist within the [scope](@) so that they will be consistent with the new version of the [terminology](@). - -## Issues/Exceptions - -## Tips - -## Example - -An account of how this process was run several times in a project is described in this [real-life example](/docs/terminology-design/methods/real-life-example) \ No newline at end of file diff --git a/docs/terminology-design/methods/1-1-discussions.md b/docs/terminology-design/methods/1-1-discussions.md deleted file mode 100644 index 0848e839bf..0000000000 --- a/docs/terminology-design/methods/1-1-discussions.md +++ /dev/null @@ -1,29 +0,0 @@ ---- -id: 1-1-discussions -// hide_table_of_contents: true -// displayed_sidebar: terminologyDesignSideBar -date: 20221120 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -# 1-1 Discussions - -This page is under construction - -This page describes techniques for establishing a mutual understanding between yourself and one other person, and possibly a common understanding.[^1] This would typically be in a setting in which you can speak to each other, as e.g., in a physical meeting or a voice/video call. - -[^1]: A mutual understanding is where you understand the position of the other, and the other understands your position, and disagreements about what is the right, or the best position, may exist. A common understanding is achieved when the both of you are in agreement. - -You should not expect that the other person is familiar with the [terminology model](@) and how it is used. Also, you should not attempt to teach the other person this model (education is a different topic). - -The overall structure of these techniques is similar, and consists of - -1. first understanding what the other person is trying to express, and -2. then expressing your own understanding of the topic. - -## Understanding what the other person is trying to express - diff --git a/docs/terminology-design/methods/criteria-elicitation.md b/docs/terminology-design/methods/criteria-elicitation.md deleted file mode 100644 index 44ac8e9d93..0000000000 --- a/docs/terminology-design/methods/criteria-elicitation.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -id: criteria-elicitation -// displayed_sidebar: terminologyDesignSideBar -date: 20221020 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' -export const mark = ({text}) => ( {text} ); - -# Criteria Elicitation - -This page is under construction - -## Summary -**Criteria Elicitation** is a process where a set of people (the participants in the process) learn what [concept(s)](@) a specific person (the protagonist[^1] of the process) has in mind when (s)he uses a particular [term](@) (the subject of the process). The process is complete when the participants can use the [term](@) in the same way as the protagonist, thereby showing that they now all have the same understanding of these [concept(s)](@). - -[^1]: We consider the protagonist of the process to also be one of its participants. - -The process assumes that it is run in a particular [context](scope@), within which all participants are motivated to actually understand the [term](@) in the meaning of the protagonist. Such contexts might include a project in which they all participate, or any other collaboration of the participants in which they work to realize certain [objectives](@), for which the actual understanding of that [term](@) is a relevant part. - -## Triggers - -There are many signals that may serve as a trigger to start this process. - -One such signal is the determination that people (that work together) start quarreling about some [term](@). Another signal could be the context in which a [terminology](@) is actually designed. [a reference to 'terminology design' is needed here] We expect that other signals may exist. - -Whatever the signal, the process should _only_ start after having ensured that all participants have a sufficient interest, and are sufficiently motivated to spend the time and effort to realize the intended result. - -## Activities - -Running the process consists of executing the following activities: - -1. Ask the protagonist to formulate the criterion that it uses to distinguish between what is, and what is not, an instance of the [term](@). A criterion is *anything* that all other participants can evaluate, i.e. use to make a judgement about whether or not something satisfies that criterion. - -2. Ask a participant (which might be the protagonist) to come up with a use-case (situation) in which the criterion would be applicable, and then ask all participants to evaluate the criteria as they understand it, and share their judgements. - -3. While the judgements differ, allow (and help) the protagonist to improve the criteria, and repeat the evaluation of the improved criteria by all participants, until all judgements are the same. - -4. Repeat steps 2 and 3, until every participant states that (s)he is convinced that (s)he can make the same distinctions as the protagonist does in arbitrary use-cases that are relevant for the context in which the process is run. - -## Issues/Exceptions - -There are a few situations that require the process execution to be deferred for some time. - -1. The protagonist may formulate a criterion that is not readily evaluable by other participants. In some cases, this issue can be resolved by asking the protagonist to reformulate the criterion. However, the criterion may also (heavily) rely on [terminology](@) that the protagonist uses, but that the other participants do not yet understand. In such cases, the participants may need to learn other [terms](@) from that [terminology](@), perhaps also how these [terms](@) relate to one another, in order to understand the [term](@) that is the subject of the process. It depends on the context in which the process is run, how the participants interact and work together, how to proceed (or terminate the process). - -2. anything else? - -## Tips - -Here are some tips to consider when running the process. - -Be friendly and respectful towards the other participants. Everyone has its own truths, backgrounds, ideas, etc. The process intends that you learn what the others think (and they will learn what you think). So don't make judgements (other than the ones based on the evaluation of the protagonists criteria). - -It may be helpful to choose a meaningless word or phrase that you can use during the process to refer to the [concept(s)](@) that the protagonist has in mind. This helps you and the other participants to stay focused on eliciting the meaning of the [term](@) as the protagonist intends, and prevents you from being distracted by the meaning that you typically associate the [term](@) with. Here are some possibilities: "Dwork", "Rilfel", "Quoth", "Mauwer", "Prakken". But you can of course invent your own. - -Help the protagonist formulate the criterion that fits his/her meaning of the [term](@). Often, the protagonist has a very good, yet unconscious idea of what the [term](@) means. Making this conscious is not a trivial task. A protagonist may be hesitant to come up with a criterion, because (s)he already feels that it isn't quite right. But it is an honest attempt. Coming up with use-cases and evaluating the criterion will provide new inspiration to improve the criterion. Start with 'easy' use-cases, and make them increasingly 'difficult' only after the easy ones - -## Example - -An account of how this process was run several times in a project is described in this [real-life example](real-life-example) \ No newline at end of file diff --git a/docs/terminology-design/methods/real-life-example.md b/docs/terminology-design/methods/real-life-example.md deleted file mode 100644 index 8881dd4d4e..0000000000 --- a/docs/terminology-design/methods/real-life-example.md +++ /dev/null @@ -1,114 +0,0 @@ ---- -id: real-life-example -// hide_table_of_contents: true -// displayed_sidebar: terminologyDesignSideBar -date: 20221020 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -# A Real-Life Example - -This page is under construction - -What follows is an account of a quarrel about the definition of 'identity', that took place in a meeting of an EU project. The account shows one of the simpler interventions that can lead to the resolve such discussions. "In the wild", things are usually not this simple, but a story like the one below does provide an idea of what we're after. - -## 1. Real-Life Observations {#1} - -The problems that a lack of [linguistic unity](@) can pose are widely recognized. The typical reflex to overcome them is to work to create a glossary, i.e. an (alphabetically sorted) list of terms, each of which is followed by a description, which may include, or be, a definition. Such glossaries are the result of discussions in which it is decided which terms are to be included, and what their definitions (descriptions) should be. Discussions about the definition of terms are not limited to the creation of glossaries. They can pop up in arbitrary situations where different people work together. - -It seems as if the mechanism is that the (most prominent) participants in the discussion each have a (strong) idea of what the definition of the term is, that these definitions differ in some significant way, and the participants then either try to convince the others of their truth, or they try to find a definition that they all agree on. It may also happen that the group leader at some point ends the discussion, with or without stating what the definition is going to be from that point forward. - -Each of these ways leads the point where not only a definition is established, but also where multiple, if not all participants are left with a feeling of dissatisfaction, if not frustration, that it still isn't right. This means that participants are unlikely to commit to using that definition, e.g. as they author documents, which implies that the quality of the document suffers as readers cannot rely on the term meaning what its definition says. - -Also, these feelings will, after some time, trigger participants to rekindle the discussion. But alas, as the method used to come to resolve the issue hasn't changed, it must be expected that the result, even if the definition itself is changed, remains the same: people remain unsatisfied, they are not committed to use the definition, and the quality of the work continues to suffer. - -## 2. Changing the discussion process - -The crux to resolving such issues is to change one's perspective from focusing on the term (and a definition to go with it), to focussing on the meanings that cause the dispute.[^1] - -In the EU project, three participants, which we will refer to as P1, P2 and P3, had a stiff argument about the definition of the term 'identity', which unfolded pretty much as described above. We then intervened by asking if they would agree to an experiment to resolve the issue. They gave their consent, so we started the following process. - -### 2.1. Get to understand the differences - -We first asked P1 to phrase the criterion that he used to distinguish between what is, and what is not, an identity. He said something like "Well, its things like passports, driving licenses, things like that, you know... ". Some people objected, saying that this is not really a criterion. We accepted the comment, and deferred the discussion to a later time.[^2] - -Going back to what P1 said, we took up a cup, asked all participants to apply the criterion as stated to the cup, and tell us what they would conclude after having applied the criterion. There are three possibilities: the cup satisfies the criterion, it does not, or it cannot be determined. There was agreement that the cup wasn't something like a passport, driving license, or things like that. We took out an ID-card, asked the same question, and again we had agreement: yes, this is something like a passport, driving license, or things like that. We then stated that this shows that all participants can make the same distinction as P1 does when they use this criterion, and hence they understand what P1 means when he talks about 'identity'. - -We then asked P2 to tell us his criterion for distinguishing identities from non-identities. He told us: "It's not the passports and such, but its what's in there: name, address, date of birth and such." Again we pointed to the cup, and there was consensus that the cup didn't satisfy the criterion. We then pointed to the ID-card, and there was consensus that the data on the card did satisfy the criterion. We concluded that we all understood what P2 meant when he talked about 'identity'. It was also clear that this meaning differs from what P1 used, and that's quite ok. - -Asking P3 for his criterion, he said: "its not all the data, but just the id-number, like a BSN (for the Netherlands), a Social Security Number, or such". It was obvious that the cup did not satisfy the criterion, and the government identifier on the ID-card did. Then, it was noticed that passports, driving licenses and the like have their own serial numbers, that also satisfy this requirement. So we asked P3 whether or not this matched his idea of identities, which he denied. Then all joined in to reformulate the criterion that would allow all of us to distinguish between what P3 did, and did not call an 'identity', as follows: "an alphanumeric string that is used to identify a natural person". - -### 2.2. Check relevance, and assign names - -There was agreement that the criteria distinguished between different things: a passport is not its data content, which again is distinct from the value in a single data field. We then asked which of these distinctions were relevant, and which were not, within the context of our project. After all, we do not want to occupy ourselves with distinctions that are irrelevant to our cooperation. There was agreement: they were all relevant. - -Since we now had three meanings (criteria) that were considered relevant for our work, it is beneficial to establish terms to refer to each of these three. From a theoretical point of view, it doesn't really matter what the terms are - you could decide to call them 'ID1', 'ID2' and 'ID3', as long as the members in the project would agree on them, and commit to using them. - -In practice, however, it is beneficial to use terms that correspond with terms that are already in practical use. But it comes with the risk that people will take these terms in the meaning that they are used to, rather than in the meaning as specified by the criteria. That's why it is necessary that all participants commit to using this 'new' terminology in the ways that they have specified, not just in their speech, but also - and particularly - when authoring documents. - -In the discussion that followed, the term: -- 'identity document' was assigned to P1's criterion, so passports, driving licenses etc. would be called an identity document; -- 'identifier' was assigned to P3's criterion, so every alphanumeric string that is used to identify a natural person, such as a BSN or a social security number, would from henceforth be called an identifier. -- 'identity' was assigned to P2's criterion, which was refined to "a set of data (attributes, claims) about a single person". - -## 3. Reflecting on the process - -Reflecting on what has happened here, there are several observations to be made. - -### 3.1. A basic activity - -One of the basic activities is that a single person (the 'protagonist' of the activity) gets to explain his understanding of the term, but not in a freewheeling fashion. He is asked to provide a specific criterion that all can later evaluate, and that distinguishes between what the person understands to be instances or non-instances of the term. This isn't easy. There is a simple test to demonstrate that what people know best is difficult for them to express in words.[^3] So we do not expect that person to come up with a first-time-right criterion; we will work with what the person provides. - -We may need to explain to the others that this process is not about judging whether or not this person is wrong, nor if he is right, nor if what he comes up with is a 'real' criterion. The only two judgements that participants are allowed to make are: -- whether or not they can evaluate the criterion that this person has provided, i.e. wether or not they will be able to answer with 'yes' or 'no' to the question of whether something that is identified in a use-case or example, satisfies the criterion, or not. -- whether or not something that is identified in a use-case or example, satisfies the criterion. - -We require the other participants to listen, and try to understand what the person is trying to express. This, too, isn't easy - not for everybody. So we also do not expect them to be able to do this, we do attempt to make them focus on -- making the two judgements as explained in the previous paragraph, and -- thinking about use-cases or examples that may provide a deeper insight into the actual distinction that the person is trying to make. - -By confining the tasks of each participant to the ones mentioned above, the discussion doesn't go all over the place.[^4] Also, because the tasks are aligned to produce a well-defined result (i.e. a criterion that all use in the same way, and produces the same judgements across the participants when applied to use-cases/examples), we see that the fighting is dramatically reduced, and often completely stops. Instead, participants feel more respected, and heard. - -This is further stimulated by having participants help the protagonist, not just by coming up with examples to 'test' the criterion, but also by proposing alternative formulations for the criterion that the protagonist is trying to express - formulations that might be easier to evaluate, or that make a more precise distinction. 'Helping the protagonist' means that the protagonist is the one that has the ultimate say in what works, and what does not. After all, it's his 'knowledge' that is being made explicit. - -### 3.2. Bringing it all together - -The basic activity is run multiple times, giving every participant the chance to be the protagonist. This results in a multitude of criteria that all have a sufficiently similar understanding of, and of which the relevance is acknowledged by all. - -Note that the process has a side effect that may be called 'team building'. When participants diligently work together to really understand each other, they will feel heard, and respected in their thinking, even if it differs from that of others. Making the differences more explicit and treating them as the real contributions that they are also helps participants to become more friendly towards each other. - -This helps in the next step, which is to come up and agree on the terms that are to be associated with the various criteria (that make the relevant distinctions). This discussion differs from the one that was stopped (and replaced by the process) in the sense that it is no longer a matter of what the 'right' or 'correct' meaning of a term is, or should be. Rather, it is a discussion about what the most appropriate word or phrase is to refer to an agreed-upon criterion. Participants would feel that it is the criterion that really matters, and the chosen term is not unimportant, but secondary. - -Time that is spent to choose terms wisely isn't wasted. After all, terms will not only be used within the group, but they will also need to be interpreted by people outside the group, e.g. those that read documents, or hear talks that originate from (one or more members of) the group. If a term is chosen that doesn't ring bells with an external audience, it means that it has to be explained all the time (which could be beneficial). If a term is chosen that is known to be used in various meanings, crafting documents or presentations need to make sure that the meaning as is intended, is actually conveyed to the audiences. - -Then, participants need to commit to using this 'new' terminology in the ways that they have specified, i.e. such that it makes the distinction as intended by the associated criterion. Participants should use it as such not just in their speech, but also - and particularly - when authoring documents. And when their utterances are intended for external audiences, they should make sure such audiences are pointed to the definitions (the criteria) that specify the intended meaning. - -### 3.3. Consolidation - -The process of coming up with criteria and assigning words/phrases to them can be concluded by - -1. writing a [glossary](@), i.e. an (alphabetically sorted) list of the [terms](@) and their [definitions](@) (criteria). However, such a [glossary](@) differs from a [glossary](https://www.merriam-webster.com/dictionary/glossary) that is created by the process described in [section 1](#1). A [glossary](@) that results from the process we advocate consists of [terms](@) that are all associated with a criterion that users can evaluate in different situations (that are relevant for the purposes of the scope of which the [glossary](@) is part) and thus determine what is, or is not, an instance of the [term](@). This is a property that is not very common to see in other [glossaries](https://www.merriam-webster.com/dictionary/glossary). - -2. further documenting each [term](@), e.g. by providing some additional descriptions that are intended to help non-participants to get to the same level of understanding of the [term](@) as the participants have acquired by discussing it, providing use-cases to test the criterion, etc. Such descriptions might contain a further elaboration of the [term](@), a few examples (e.g., from the use-cases), a specification of the purposes(s) for which the [term](@) is particularly useful, etc. - -3. documenting the coherence between the [terms](@), e.g. as one or more [mental models](pattern@). They serve similar purposes as the additional descriptions of [terms](@), but rather than drilling down on the meaning of a single [term](@), they focus on the relations that [terms](@) have between each other, and constraints that apply. [Patterns](@) thus provide additional semantics that are difficult to capture in their entirety in the [definition](@) and/or further description of single [terms](@). - -### 3.4. Tools for consolidation - -Many tools exist to document various things, particularly in the context of IT, where the use of e.g. GIT repositories is common. Tools such as [Docusaurus](https://docusaurus.io/docs), [GitHub Pages](https://pages.github.com/), [Jekyll](https://jekyllrb.com/), and [many more](https://www.google.com/search?q=static+site+generators). These tools can be used to write a [glossary](@), and document [terms](@) and [mental models](@). - -Also, a toolbox called [TEv2](@) is being constructed that aims to provide support for this, e.g. by automatically generating [glossaries](@), and providing enabling authors to refer to specific [definitions](@) and descriptions of [terms](@) that they use, making it easier for readers of that documentation to know the meaning thereof that the author intended. - -## Notes - -[^1]: See also: R. Joosten, '[On Terminology and the Resolution of Related Issues](https://www.researchgate.net/publication/352560909_On_Terminology_and_the_Resolution_of_Related_Issues)', TNO, Technical Report R11793, DOI: 10.13140/RG.2.2.17546.18888. - -[^2]: The discussion about what is (not) a 'criterion' is a different topic. We don't want to discuss two definitions at the same time. - -[^3]: People that are native speakers of a language, can usually demonstrate their knowledge of the specifications of that language (its grammar), by showing that they can (1) determine whether or not a sentence in that language is grammatically correct, (2) correct the sentences that were incorrect and (3) come up with (say) 5 alternatives for correcting an incorrect sentence, and picking out 'the most beautiful', or 'the best' one. However, when asked whether they could write down the specifications such that the result is consistent, coherent, complete, cogent, congruent - and other c-words that refer to characteristics that specifications are typically expected to have, they will say 'no'. Even worse: if they are presented a booklet that is about the grammar of their mother's tongue, and are asked to determine whether or not it specifies that grammar in a consistent, coherent, complete, etc. way, they will also decline. - -[^4]: Confining what participants can do helps to keep the activity focused. This is particularly important if the process is under time constraints (which most of the time is the case). There are various techniques that contribute to keeping the focus, two of which are already mentioned. Another technique is to refuse to talk about/process any use-case/example that is irrelevant for the objectives that the participants, as a group, try to realize. diff --git a/docs/terminology-design/methods/terminology-process.md b/docs/terminology-design/methods/terminology-process.md deleted file mode 100644 index 44ee1090ff..0000000000 --- a/docs/terminology-design/methods/terminology-process.md +++ /dev/null @@ -1,88 +0,0 @@ ---- -id: terminology-process -// displayed_sidebar: terminologyDesignSideBar -date: 20221020 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -# Terminology Process - -This page is under construction - -## Summary -The **terminology process** is a method for recognizing misunderstandings as such, and creating or maintaining [definitions](@) that resolve them. It helps [parties](@) that work together to realize certain [objectives](@) (in some [scope](@)) by enabling them to establish a [terminology](@) that has the property that every party has the same understanding of each of its [terms](@), and that each of these [terms](@) is relevant for the realizations of these [objectives](@). - -## Prerequisites -This process focuses on the creation and maintenance of qualitatively good [definitions](@), i.e. [definitions](@) that satisfy the following quality criteria: -- the [definition](@) is associated with a [scope](@) that is explicitly defined, i.e. any [party](@) can unambiguously determine whether or not the definition applies; -- the [criteria](https://www.lexico.com/definition/criterion) of the definition are well-formed, meaning that all stakeholders make the same judgements c.q. reach the same conclusions when using these criteria in a given situation that is relevant within the scope. -- the definition is relevant, which means that stakeholders have identified cases that demonstrate how the use of this definition helps them realize their objectives and/or address issues that prevent them from doing so, or they have agreed that relevance is obvious. -- there is consensus between the stakeholders regarding the [term](@) - the actual word or phrase - that is to be used to refer to (unidentified, or arbitrary, or specific) [entities](@) that satisfy the criterion. - -This process does not prohibit that definitions may satisfy other criteria, or be associated with other attributes so that they may become better suited to serve other purposes as well. For example, a definition that is to be used in an educational context may be required to come with examples, and/or explanations about why the distinction is made as it is. - -## Creating or Changing a Definition - -The process (step) for creating and/or changing a definition starts with a request to this end. - -Processing this request, which includes deciding whether or not to service it in the first place, should be done by one or more stakeholders of the term. After all, they are the ones that contribute to the realization of the objectives for which the term was defined, and hence need to ensure they can (keep) work(ing) with it.[^note] - -This doesn't mean that others Of course, it doesn't mean that others cannot have good ideas, but whether or not that is the case is for the stakeholders to decide. Too often do we see e.g. people adding terms to a glossary for purposes that don't serve the objectives. - -We do not prescribe any specific way for stakeholders to process the request. We only state the conditions that anyone can check to see if the work is done, which is the case when the definition qualifies as a 'good definition' according to the criteria stated above. Thus, stakeholders can do whatever they deem appropriate, as long as the end result satisfies these criteria. - -If the set of stakeholders is too large to be practical for satisfying these criteria, they may appoint one (or a small committee) of them as a 'terminology officer' or 'curator', i.e. the one that is tasked with processing such requests and bringing that processing to a satisfactory end. - -## Conflict Mediation and Resolution - -We have experienced many situations in which terms were not used 'in the right way'. This is not problematic per se. Going back to the example of the coffee cup, one of the students may observe that coffee is being served in something that he does not consider to be a cup. If he reacts by saying how surprised he is to find out that cups are more varied than he thought so far, this is an expression of having obtained a new insight, and having learned in an enjoyable fashion. From our perspective, he values the importance of the criterion higher than the importance of being right in the definition that he has (unconsciously) used himself. - -However, we often find that people feel strongly about what is the 'right' definition of a term, even though they have problems in providing a good definition, i.e. one that is both relevant and well-formed. This often leads to debates that in the end do not have a satisfactory conclusion. - -If you find yourself in such a discussion, there are several things that you can do to revert this situation. The first thing is to verify that the participants are sufficiently motivated to have an outcome that is good for all – even if that means they will have to acknowledge that they were not right all the way. We assume that a sufficiently motivated group of participants can agree that definitions should have the properties that we have defined for being a good definition. You may want to explicitly establish this assumption, and explain that these properties prevent misunderstandings, cater for better cooperation as you get a common 'picture' of what you are doing, and what is relevant for that and what is not. And yes, it may seem to take more time than usual. However, we see this as a sure sign that spending this time now and resolving the issue will save us multiple such times where the issue is not resolved in a manner that is satisfactory to all participants: such issues will persist in popping up. Some people may need to experience this for themselves before accepting that this is the case. - -Even after having established that participants are motivated to come to a good definition, participants may have strong feelings about the meaning of terms or the phrasing of a definition, and object to review that. In such cases, it may help to state the scope of the definition that you are trying to agree on, e.g. being a project you all work on, or the discussion that you are having. Then, you can explain that the definition you are trying to pin down is only applicable in that scope, which means that strong feelings about the meaning of the term or the phrasing of a definition are ok in other context, and that the definition for the term that you are trying to define does not pose a threat to these contexts. We have seen this intervention have a relativizing effect on people, as it allows them to participate without having to give up their opinions (for other contexts). - -Another intervention that you can do when the scope is clear, yet the discussions go all over the place, is clearly stating when you are trying to formulate a criterion and assess its well-formedness, and when you are establishing the relevance of the distinction that you attempt to make. When assessing relevance, the task is to come up with situations that call for the need to make the envisaged distinction. But you should not surrender to the temptation to already apply (one of the) criteria that may lie around. When you are trying to formulate or choose a criterion and assess its well-formedness, the task is to throw these (relevant) situations at the criterion, and ONLY find out whether or not stakeholders make the same distinction. As you alternate between these two tasks, you may find that at some point in time, - -- convergence takes place, i.e. the proposed criteria increasingly become well-formed, and increasingly make the distinction that you are after. You have a good definition! -- it dawns on you that it is not one, but other distinctions need be made as well. In the example of the wine students, they may find out that they do not only need a definition for 'glass', but that they need other terms in order to distinguish between the various kinds of glasses they need for drinking different wines.[^IAU] You split up the discussion in as many discussions as you want to make distinctions. -- no convergence takes place at all. You are probably trying to make distinctions that in the end do not make any sense. Take a break, try to get some fresh/foolish ideas, and try again from there. - -## Background - -A common way to foster mutual understanding is to define terms. The idea is that if we agree to define a term in some way, and use that term accordingly, we avoid misunderstandings. Indeed, many terminologies (lists of definitions) have been established, in many varieties (e.g. glossaries, dictionaries, etc.) in an attempt to achieve this objective. The fact that debates about well-known terms keep popping up over and over again both underlines the importance of this work and suggests that improvements are called for. - -We propose an approach that focuses on the effects that we want definitions to have in discussions, the most important one of which is that people that use a term in a discussion agree as to what is, and what is not an instance of the term, and that this agreement extends to multiple, different situations. - -Note that this effect is limited to the scope of a discussion, which would allow the same term to have a different meaning/interpretation in other discussions (as is common practice). Terminologies however are typically meant to be used in large(r) scopes, where people pursue specific objectives. For example, a terminology may be needed for creating, maintaining and using (a set of) standards, or an IT system. - -We postulate that the use of a specific terminology is limited to a (set of) scope(s) within which specific objectives are being pursued. Doing this allows us to discuss the relevance of terms within a scope: a definition that does not help people to realize the objectives of the scope has no place in the terminology of that scope. Conversely, any distinction that helps people to realize one or more of the objectives should be made explicit, and assigned a term. This makes terminology the invaluable asset that we feel it should be. - -Within this document, we use the term 'stakeholder (of a terminology)' to refer to a person that contributes to realizing objectives of some scope for which that terminology exists, or is being developed/maintained. Having this notion allows us to distinguish between people that have a working interest in the terms defined therein, and those that do not. We will only allow stakeholders of a terminology to participate in discussions to create, update or delete terms therein. - -Terms that are defined in a terminology use usually classifications of things we know to exist. For example, 'cup' represents a class of things that have specific characteristics. If stakeholders want to agree on what a cup is, they should devise a criterion that allows them to distinguish between things that are a cup, and things that are not. One part of a definition should thus be a criterion by which any stakeholder can make this judgement. - -We say that a criterion is 'well-formed' if it has the property that all stakeholders make the same judgement in a given, yet arbitrary case. So if stakeholders use a well-formed criterion for 'cup', then you can present any item to them, and every time they will agree as to whether or not this item is a cup. The property of being well-formed is important for these criteria, because it ensures that stakeholders have the same idea about the meaning of a term. - -Criteria that are well-formed in one context may not be well-formed in another context. In the context of a café in which some students want to converse while drinking a cup of coffee, the criterion 'anything that can contain coffee and that a person can drink out of' would be well-formed. In the context of a space station in which some astronauts want to converse while drinking a cup of coffee, this criterion may not be appropriate as it would include cups that spill their coffee because of the lack of gravity[^NASA]. Therefore, another part of a definition should be a reference to the scope(s) within which it is applied. - -We say that a criterion is 'relevant' if it has the property that all stakeholders agree – possibly for different reasons – that the distinction it makes helps them to realize their objectives and/or address issues that prevent them from doing so. Testing for this property (i.e. asking the stakeholders whether or not they think it helps to realize objectives and/or address issues[^test]) ensures that the criterion does not need to make distinctions that, while relevant in other scopes, are irrelevant in the scope in which it is established. - -Obviously, criteria that are relevant in one context may not not be relevant in another context. For example, in the context of a chic restaurant in which some students want to have a good time, conversing with one another and drinking glasses of wine, the criterion for a glass: 'anything that can contain wine and that a person can drink out of' would be relevant. In the context of that same restaurants in which the same students want to taste wine as part of their training to become a sommelier, this criterion is no longer relevant. - -## Notes - -[^note]: We have often seen (changes in) definitions of terms being contributed by well-intentioned people, the result of which didn't qualify as a 'good definition', amongst others because they were not stakeholders as we see them. - -[^IAU]: A famous example of discussions and the use of definitions that constitute of criteria is that in the IAU, about (dwarf) planets. While it is a good example of how definitions should be used, it also shows that it is not the holy grail. See: -- see: https://en.wikipedia.org/wiki/Dwarf_planet for an account of what happened and for the resolution; -- IAU (August 24, 2006). "[Definition of a Planet in the Solar System: Resolutions 5 and 6](https://www.iau.org/static/resolutions/Resolution_GA26-5-6.pdf)". IAU 2006 General Assembly. International Astronomical Union. Retrieved March 8, 2018. – discussions - -[^NASA]: NASA has designed so-called 'space cups' for drinking liquids such a s coffee in the International Space Station ISS. See https://www.nasa.gov/mission_pages/station/research/experiments/2029.html. - -[^test]: If you test a criterion by simply asking stakeholders to assert that the criteria is relevant, you run the [risk](@) that they have their own interpretation of the term 'relevant'. In order to mitigate this [risk](@), you should either define 'relevance (of a criterion that is used in a definition)' as the property of helping stakeholders in the scope of that definition to to realize their objectives and/or address issues that prevent them from doing so, or you should ask the question as we stated here. \ No newline at end of file diff --git a/docs/terminology-design/methods/why-design-thinking-works.txt b/docs/terminology-design/methods/why-design-thinking-works.txt deleted file mode 100644 index faf9207711..0000000000 --- a/docs/terminology-design/methods/why-design-thinking-works.txt +++ /dev/null @@ -1,133 +0,0 @@ ---- -id: why-design-thinking-works -// hide_table_of_contents: true -// displayed_sidebar: terminologyDesignSideBar -date: 20221020 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -# Why Design Thinking Works - -This text is a cut-and-past from Jeanne Liedtka, '[Why Design Thinking Works](https://hbr.org/2018/09/why-design-thinking-works)', Harvard Business Review, September-October 2018. - -## Summary - -While we know a lot about practices that stimulate new ideas, innovation teams often struggle to apply them. Why? Because people’s biases and entrenched behaviors get in the way. In this article a Darden professor explains how design thinking helps people overcome this problem and unleash their creativity. - -Though ostensibly geared to understanding and molding the experiences of customers, design thinking also profoundly reshapes the experiences of the innovators themselves. For example, immersive customer research helps them set aside their own views and recognize needs customers haven’t expressed. Carefully planned dialogues help teams build on their diverse ideas, not just negotiate compromises when differences arise. And experiments with new solutions reduce all stakeholders’ fear of change. - -At every phase—customer discovery, idea generation, and testing—a clear structure makes people more comfortable trying new things, and processes increase collaboration. Because it combines practical tools and human insight, design thinking is a social technology—one that the author predicts will have an impact as large as an earlier social technology, total quality management. - -**Occasionally, a new way of organizing work** leads to extraordinary improvements. Total quality management did that in manufacturing in the 1980s by combining a set of tools—kanban cards, quality circles, and so on—with the insight that people on the shop floor could do much higher level work than they usually were asked to. That blend of tools and insight, applied to a work process, can be thought of as a _social technology_. - -In a recent seven-year study in which I looked in depth at 50 projects from a range of sectors, including business, health care, and social services, I have seen that another social technology, design thinking, has the potential to do for innovation exactly what TQM did for manufacturing: unleash people’s full creative energies, win their commitment, and radically improve processes. By now most executives have at least heard about design thinking’s tools—ethnographic research, an emphasis on reframing problems and experimentation, the use of diverse teams, and so on—if not tried them. But what people may not understand is the subtler way that design thinking gets around the human biases (for example, rootedness in the status quo) or attachments to specific behavioral norms (“That’s how we do things here”) that time and again block the exercise of imagination. - -In this article I’ll explore a variety of human tendencies that get in the way of innovation and describe how design thinking’s tools and clear process steps help teams break free of them. Let’s begin by looking at what organizations need from innovation—and at why their efforts to obtain it often fall short. - -## The Challenges of Innovation - -To be successful, an innovation process must deliver three things: superior solutions, lower risks and costs of change, and employee buy-in. Over the years businesspeople have developed useful tactics for achieving those outcomes. But when trying to apply them, organizations frequently encounter new obstacles and trade-offs. - -**Superior solutions.** Defining problems in obvious, conventional ways, not surprisingly, often leads to obvious, conventional solutions. _Asking a more interesting question_ can help teams discover more-original ideas. The risk is that some teams may get indefinitely hung up exploring a problem, while action-oriented managers may be too impatient to take the time to figure out what question they should be asking. - -It’s also widely accepted that solutions are much better when they incorporate _user-driven criteria_. Market research can help companies understand those criteria, but the hurdle here is that it’s hard for customers to know they want something that doesn’t yet exist. - -Finally, bringing _diverse voices_ into the process is also known to improve solutions. This can be difficult to manage, however, if conversations among people with opposing views deteriorate into divisive debates. - -**Lower risks and costs.** Uncertainty is unavoidable in innovation. That’s why innovators often build a _portfolio of options_. The trade-off is that too many ideas dilute focus and resources. To manage this tension, innovators must be willing to let go of bad ideas—to “call the baby ugly,” as a manager in one of my studies described it. Unfortunately, people often find it easier to kill the creative (and arguably riskier) ideas than to kill the incremental ones.Employee buy-in. An innovation won’t succeed unless a company’s employees get behind it. The surest route to winning their support is to involve them in the process of generating ideas. The danger is that the involvement of many people with different perspectives will create chaos and incoherence. - -Underlying the trade-offs associated with achieving these outcomes is a more fundamental tension. In a stable environment, efficiency is achieved by driving variation out of the organization. But in an unstable world, variation becomes the organization’s friend, because it opens new paths to success. However, who can blame leaders who must meet quarterly targets for doubling down on efficiency, rationality, and centralized control? - -To manage all the trade-offs, organizations need a social technology that addresses these behavioral obstacles as well as the counterproductive biases of human beings. And as I’ll explain next, design thinking fits that bill. - -## The Beauty of Structure - -Experienced designers often complain that design thinking is too structured and linear. And for them, that’s certainly true. But managers on innovation teams generally are not designers and also aren’t used to doing face-to-face research with customers, getting deeply immersed in their perspectives, co-creating with stakeholders, and designing and executing experiments. Structure and linearity help managers try and adjust to these new behaviors. - -As Kaaren Hanson, formerly the head of design innovation at Intuit and now Facebook’s design product director, has explained: “Anytime you’re trying to change people’s behavior, you need to start them off with a lot of structure, so they don’t have to think. A lot of what we do is habit, and it’s hard to change those habits, but having very clear guardrails can help us.” - -Organized processes keep people on track and curb the tendency to spend too long exploring a problem or to impatiently skip ahead. They also instill confidence. Most humans are driven by a fear of mistakes, so they focus more on preventing errors than on seizing opportunities. They opt for inaction rather than action when a choice risks failure. But there is no innovation without action—so psychological safety is essential. The physical props and highly formatted tools of design thinking deliver that sense of security, helping would-be innovators move more assuredly through the discovery of customer needs, idea generation, and idea testing. - -In most organizations the application of design thinking involves seven activities. Each generates a clear output that the next activity converts to another output until the organization arrives at an implementable innovation. But at a deeper level, something else is happening—something that executives generally are not aware of. Though ostensibly geared to understanding and molding the experiences of customers, each design-thinking activity also reshapes the experiences of the _innovators themselves_ in profound ways. - -## Customer Discovery - -Many of the best-known methods of the design-thinking discovery process relate to identifying the “job to be done.” Adapted from the fields of ethnography and sociology, these methods concentrate on examining what makes for a meaningful customer journey rather than on the collection and analysis of data. This exploration entails three sets of activities: - -**Immersion.** Traditionally, customer research has been an impersonal exercise. An expert, who may well have preexisting theories about customer preferences, reviews feedback from focus groups, surveys, and, if available, data on current behavior, and draws inferences about needs. The better the data, the better the inferences. The trouble is, this grounds people in the already articulated needs that the data reflects. They see the data through the lens of their own biases. And they don’t recognize needs people have not expressed. - -## Shaping the Innovator’s Journey - -What makes design thinking a social technology is its ability to counteract the biases of innovators and change the way they engage in the innovation process. - -| **Problem** | **Design thinking** | **Improved outcome** | -| ----------- | ------------------- | -------------------- | -| Innovators are trapped in their own expertise and experience. | Design thinking provides immersion in the user’s experience, shifting an innovator’s mindset toward… | …a better understanding of those being designed for. | -| Innovators are overwhelmed by the volume and messiness of qualitative data. | Design thinking makes sense of data by organizing it into themes and patterns, pointing the innovator toward… | …new insights and possibilities. | -| Innovators are divided by differences in team members’ perspectives. | Design thinking builds alignment as insights are translated into design criteria, moving an innovation team toward… | …convergence around what really matters to users. | -| Innovators are confronted by too many disparate but familiar ideas. | Design thinking encourages the emergence of fresh ideas through a focused inquiry, shifting team members toward… | …a limited but diverse set of potential new solutions. | -| Innovators are constrained by existing biases about what does or doesn’t work. | Design thinking fosters articulation of the conditions necessary to each idea’s success and transitions a team toward… | …clarity on make-or-break assumptions that enables the design of meaningful experiments. | -| Innovators are lacking a shared understanding of new ideas and often unable to get good feedback from users. | Design thinking offers pre-experiences to users through very rough prototypes that help innovators get… | …accurate feedback at low cost and an understanding of potential solutions’ true value. | -| Innovators are afraid of change and ambiguity surrounding the new future. | Design thinking delivers learning in action as experiments engage staff and users, helping them build… | …a shared commitment and confidence in the new product or strategy. | - -Design thinking takes a different approach: Identify hidden needs by having the innovator live the customer’s experience. Consider what happened at the Kingwood Trust, a UK charity helping adults with autism and Asperger’s syndrome. One design team member, Katie Gaudion, got to know Pete, a nonverbal adult with autism. The first time she observed him at his home, she saw him engaged in seemingly damaging acts—like picking at a leather sofa and rubbing indents in a wall. She started by documenting Pete’s behavior and defined the problem as how to prevent such destructiveness. - -But on her second visit to Pete’s home, she asked herself: What if Pete’s actions were motivated by something other than a destructive impulse? Putting her personal perspective aside, she mirrored his behavior and discovered how satisfying his activities actually felt. “Instead of a ruined sofa, I now perceived Pete’s sofa as an object wrapped in fabric that is fun to pick,” she explained. “Pressing my ear against the wall and feeling the vibrations of the music above, I felt a slight tickle in my ear whilst rubbing the smooth and beautiful indentation… So instead of a damaged wall, I perceived it as a pleasant and relaxing audio-tactile experience.” - -Katie’s immersion in Pete’s world not only produced a deeper understanding of his challenges but called into question an unexamined bias about the residents, who had been perceived as disability sufferers that needed to be kept safe. Her experience caused her to ask herself another new question: Instead of designing just for residents’ disabilities and safety, how could the innovation team design for their strengths and pleasures? That led to the creation of living spaces, gardens, and new activities aimed at enabling people with autism to live fuller and more pleasurable lives. - -**Sense making.** Immersion in user experiences provides raw material for deeper insights. But finding patterns and making sense of the mass of qualitative data collected is a daunting challenge. Time and again, I have seen initial enthusiasm about the results of ethnographic tools fade as nondesigners become overwhelmed by the volume of information and the messiness of searching for deeper insights. It is here that the structure of design thinking really comes into its own. - -One of the most effective ways to make sense of the knowledge generated by immersion is a design-thinking exercise called the Gallery Walk. In it the core innovation team selects the most important data gathered during the discovery process and writes it down on large posters. Often these posters showcase individuals who have been interviewed, complete with their photos and quotations capturing their perspectives. The posters are hung around a room, and key stakeholders are invited to tour this gallery and write down on Post-it notes the bits of data they consider essential to new designs. The stakeholders then form small teams, and in a carefully orchestrated process, their Post-it observations are shared, combined, and sorted by theme into clusters that the group mines for insights. This process overcomes the danger that innovators will be unduly influenced by their own biases and see only what they want to see, because it makes the people who were interviewed feel vivid and real to those browsing the gallery. It creates a common database and facilitates collaborators’ ability to interact, reach shared insights together, and challenge one another’s individual takeaways—another critical guard against biased interpretations. - -**Alignment.** The final stage in the discovery process is a series of workshops and seminar discussions that ask in some form the question, If anything were possible, what job would the design do well? The focus on possibilities, rather than on the constraints imposed by the status quo, helps diverse teams have more-collaborative and creative discussions about the design criteria, or the set of key features that an ideal innovation should have. Establishing a spirit of inquiry deepens dissatisfaction with the status quo and makes it easier for teams to reach consensus throughout the innovation process. And down the road, when the portfolio of ideas is winnowed, agreement on the design criteria will give novel ideas a fighting chance against safer incremental ones. - -Consider what happened at Monash Health, an integrated hospital and health care system in Melbourne, Australia. Mental health clinicians there had long been concerned about the frequency of patient relapses—usually in the form of drug overdoses and suicide attempts—but consensus on how to address this problem eluded them. In an effort to get to the bottom of it, clinicians traced the experiences of specific patients through the treatment process. One patient, Tom, emerged as emblematic in their study. His experience included three face-to-face visits with different clinicians, 70 touchpoints, 13 different case managers, and 18 handoffs during the interval between his initial visit and his relapse. - -The team members held a series of workshops in which they asked clinicians this question: Did Tom’s current care exemplify why they had entered health care? As people discussed their motivations for becoming doctors and nurses, they came to realize that improving Tom’s outcome might depend as much on their sense of duty to Tom himself as it did on their clinical activity. Everyone bought into this conclusion, which made designing a new treatment process—centered on the patient’s needs rather than perceived best practices—proceed smoothly and successfully. After its implementation, patient-relapse rates fell by 60%. - -## Idea Generation - -Once they understand customers’ needs, innovators move on to identify and winnow down specific solutions that conform to the criteria they’ve identified. - -**Emergence.** The first step here is to set up a dialogue about potential solutions, carefully planning who will participate, what challenge they will be given, and how the conversation will be structured. After using the design criteria to do some individual brainstorming, participants gather to share ideas and build on them creatively—as opposed to simply negotiating compromises when differences arise. - -When Children’s Health System of Texas, the sixth-largest pediatric medical center in the United States, identified the need for a new strategy, the organization, led by the vice president of population health, Peter Roberts, applied design thinking to reimagine its business model. During the discovery process, clinicians set aside their bias that what mattered most was medical intervention. They came to understand that intervention alone wouldn’t work if the local population in Dallas didn’t have the time or ability to seek out medical knowledge and didn’t have strong support networks—something few families in the area enjoyed. The clinicians also realized that the medical center couldn’t successfully address problems on its own; the community would need to be central to any solution. So Children’s Health invited its community partners to codesign a new wellness ecosystem whose boundaries (and resources) would stretch far beyond the medical center. Deciding to start small and tackle a single condition, the team gathered to create a new model for managing asthma. - -The session brought together hospital administrators, physicians, nurses, social workers, parents of patients, and staff from Dallas’s school districts, housing authority, YMCA, and faith-based organizations. First, the core innovation team shared learning from the discovery process. Next, each attendee thought independently about the capabilities that his or her institution might contribute toward addressing the children’s problems, jotting down ideas on sticky notes. Then each attendee was invited to join a small group at one of five tables, where the participants shared individual ideas, grouped them into common themes, and envisioned what an ideal experience would look like for the young patients and their families. - -Champions of change usually emerge from these kinds of conversations, which greatly improves the chances of successful implementation. (All too often, good ideas die on the vine in the absence of people with a personal commitment to making them happen.) At Children’s Health, the partners invited into the project galvanized the community to act and forged and maintained the relationships in their institutions required to realize the new vision. Housing authority representatives drove changes in housing codes, charging inspectors with incorporating children’s health issues (like the presence of mold) into their assessments. Local pediatricians adopted a set of standard asthma protocols, and parents of children with asthma took on a significant role as peer counselors providing intensive education to other families through home visits. - -**Articulation.** Typically, emergence activities generate a number of competing ideas, more or less attractive and more or less feasible. In the next step, articulation, innovators surface and question their implicit assumptions. Managers are often bad at this, because of many behavioral biases, such as overoptimism, confirmation bias, and fixation on first solutions. When assumptions aren’t challenged, discussions around what will or won’t work become deadlocked, with each person advocating from his or her own understanding of how the world works. - -In contrast, design thinking frames the discussion as an inquiry into what would have to be true about the world for an idea to be feasible. (See “[Management Is Much More Than a Science](https://hbr.org/2017/09/management-is-much-more-than-a-science),” by Roger L. Martin and Tony Golsby-Smith, HBR, September–October 2017.) An example of this comes from the Ignite Accelerator program of the U.S. Department of Health and Human Services. At the Whiteriver Indian reservation hospital in Arizona, a team led by Marliza Rivera, a young quality control officer, sought to reduce wait times in the hospital’s emergency room, which were sometimes as long as six hours. - -The team’s initial concept, borrowed from Johns Hopkins Hospital in Baltimore, was to install an electronic kiosk for check-in. As team members began to apply design thinking, however, they were asked to surface their assumptions about why the idea would work. It was only then that they realized that their patients, many of whom were elderly Apache speakers, were unlikely to be comfortable with computer technology. Approaches that worked in urban Baltimore would not work in Whiteriver, so this idea could be safely set aside. - -At the end of the idea generation process, innovators will have a portfolio of well-thought-through, though possibly quite different, ideas. The assumptions underlying them will have been carefully vetted, and the conditions necessary for their success will be achievable. The ideas will also have the support of committed teams, who will be prepared to take on the responsibility of bringing them to market. - -## The Testing Experience - -Companies often regard prototyping as a process of fine-tuning a product or service that has already largely been developed. But in design thinking, prototyping is carried out on far-from-finished products. It’s about users’ iterative experiences with a work in progress. This means that quite radical changes—including complete redesigns—can occur along the way. - -**Pre-experience.** Neuroscience research indicates that helping people “pre-experience” something novel—or to put it another way, _imagine_ it incredibly vividly—results in more-accurate assessments of the novelty’s value. That’s why design thinking calls for the creation of basic, low-cost artifacts that will capture the essential features of the proposed user experience. These are not literal prototypes—and they are often much rougher than the “minimum viable products” that lean start-ups test with customers. But what these artifacts lose in fidelity, they gain in flexibility, because they can easily be altered in response to what’s learned by exposing users to them. And their incompleteness invites interaction. - -Such artifacts can take many forms. The layout of a new medical office building at Kaiser Permanente, for example, was tested by hanging bedsheets from the ceiling to mark future walls. Nurses and physicians were invited to interact with staffers who were playing the role of patients and to suggest how spaces could be adjusted to better facilitate treatment. At Monash Health, a program called Monash Watch—aimed at using telemedicine to keep vulnerable populations healthy at home and reduce their hospitalization rates—used detailed storyboards to help hospital administrators and government policy makers envision this new approach in practice, without building a digital prototype. - -**Learning in action.** Real-world experiments are an essential way to assess new ideas and identify the changes needed to make them workable. But such tests offer another, less obvious kind of value: They help reduce employees’ and customers’ quite normal fear of change. -Consider an idea proposed by Don Campbell, a professor of medicine, and Keith Stockman, a manager of operations research at Monash Health. As part of Monash Watch, they suggested hiring laypeople to be “telecare” guides who would act as “professional neighbors,” keeping in frequent telephone contact with patients at high risk of multiple hospital admissions. Campbell and Stockman hypothesized that lower-wage laypeople who were carefully selected, trained in health literacy and empathy skills, and backed by a decision support system and professional coaches they could involve as needed could help keep the at-risk patients healthy at home. - -Their proposal was met with skepticism. Many of their colleagues held a strong bias against letting anyone besides a health professional perform such a service for patients with complex issues, but using health professionals in the role would have been unaffordable. Rather than debating this point, however, the innovation team members acknowledged the concerns and engaged their colleagues in the codesign of an experiment testing that assumption. Three hundred patients later, the results were in: Overwhelmingly positive patient feedback and a demonstrated reduction in bed use and emergency room visits, corroborated by independent consultants, quelled the fears of the skeptics. - -## . . . - -As we have seen, the structure of design thinking creates a natural flow from research to rollout. Immersion in the customer experience produces data, which is transformed into insights, which help teams agree on design criteria they use to brainstorm solutions. Assumptions about what’s critical to the success of those solutions are examined and then tested with rough prototypes that help teams further develop innovations and prepare them for real-world experiments. - -Along the way, design-thinking processes counteract human biases that thwart creativity while addressing the challenges typically faced in reaching superior solutions, lowered costs and risks, and employee buy-in. Recognizing organizations as collections of human beings who are motivated by varying perspectives and emotions, design thinking emphasizes engagement, dialogue, and learning. By involving customers and other stakeholders in the definition of the problem and the development of solutions, design thinking garners a broad commitment to change. And by supplying a structure to the innovation process, design thinking helps innovators collaborate and agree on what is essential to the outcome at every phase. It does this not only by overcoming workplace politics but by shaping the experiences of the innovators, and of their key stakeholders and implementers, at every step. _That_ is social technology at work. - ---- - -A version of this article appeared in the September–October 2018 issue (pp.72–79) of _Harvard Business Review_. - -**Jeanne Liedtka** (liedtkaj@darden.virginia.edu) is professor of business administration at the University of Virginia’s Darden School of Business. diff --git a/docs/terminology-design/mrgen.py b/docs/terminology-design/mrgen.py deleted file mode 100644 index d6f056c320..0000000000 --- a/docs/terminology-design/mrgen.py +++ /dev/null @@ -1,257 +0,0 @@ -# ChatGPT intro: I'm trying to build a machine readable glossary (MRG) from markdown files. The structure of the files and other things is found in the SAF.yaml file, e.g. where these markdown files are located (`curatedir`), and where the MRG is to be written (`glossarydir`). Here is the script I use: - -import argparse -import os -import yaml -import copy -from ruamel.yaml import YAML -import re -import glob -import datetime -import sys - -# Create Terminology section - -def construct_terminology_section(saf_data, version_tag): - today = datetime.datetime.now().strftime("%Y%m%d") - yaml = YAML() - yaml.indent(mapping=2, sequence=4, offset=2) - - if not version_tag: - raise Exception(f"Error: `version_tag` should have been provided, but is not") - - versions = saf_data.get("versions", []) - found_version = None - for version in versions: - vsntag = version.get("vsntag", "") - altvsntags = version.get("altvsntags", []) - if vsntag == version_tag or version_tag in altvsntags: - found_version = version - break - - print(yaml.dump(found_version, sys.stdout)) - - if not found_version: - raise Exception(f"Error: Invalid version_tag provided: {version_tag}") - - terminology_section = { - "scopetag": saf_data.get("scope", {}).get("scopetag"), - "scopedir": saf_data.get("scope", {}).get("scopedir"), - "curatedir": saf_data.get("scope", {}).get("curatedir"), - "glossarydir": saf_data.get("scope", {}).get("glossarydir"), - "website": saf_data.get("scope", {}).get("website"), - "navpath": saf_data.get("scope", {}).get("navpath"), - "license": saf_data.get("scope", {}).get("license", ""), - "version": vsntag, - "altversions": altvsntags, - "date": today - } - - if not terminology_section["scopetag"]: - raise Exception("Error: 'scopetag' field missing in SAF.yaml.") - - if not terminology_section["scopedir"]: - raise Exception("Error: 'scopedir' field missing in SAF.yaml.") - - if not terminology_section["curatedir"]: - raise Exception("Error: 'curatedir' field missing in SAF.yaml.") - - # Set other missing fields to empty string - terminology_section.setdefault("website", "") - terminology_section.setdefault("navpath", "") - terminology_section.setdefault("license", "") - - return terminology_section - -# Create Scopes section - -def construct_scopes_section(saf_data): - # Code to generate the scopes section - scopes_section = { - "scopes": [] # Scopes section data - } - return scopes_section - -# Create Entries section - -def process_markdown_file(md_file, saf_data, error_messages): - with open(md_file, 'r', encoding='utf-8') as f: - content = f.read() - - # Find front matter - start_index = content.find('---') - end_index = content.find('---', start_index + 3) - - if start_index == -1 or end_index == -1: - error_messages.append(f"Error: No YAML front matter found in {md_file}") - return None - - front_matter = content[start_index+3:end_index].strip() - - # Construct MRG entry - yaml = YAML() - try: - mrg_entry = yaml.load(front_matter) - except Exception as e: - error_messages.append(f"Error in YAML front matter of {md_file}: {str(e)}") - return None - - if not isinstance(mrg_entry, dict): - error_messages.append(f"Error: Invalid YAML front matter in {md_file}") - return None - - # Raise error if 'term' is missing - if 'term' not in mrg_entry: - error_messages.append(f"Error: 'term' field is missing in {md_file}") - return None - - mrg_entry['scopetag'] = saf_data.get("scope", {}).get("scopetag") # Use the actual scopetag value - mrg_entry['locator'] = '/' + mrg_entry['term'] - mrg_entry['navurl'] = '/' + mrg_entry['term'] - - # Find heading tags in the markdown body - body_content = content[end_index+3:] - heading_tags = [] - heading_regex = r'^(?P#+)\s*(?P.*?)\s*(?:{#(?P[A-Za-z0-9-_]+)})?$' - - for match in re.finditer(heading_regex, body_content, re.MULTILINE): - heading_level = len(match.group('heading_level')) - heading_text = match.group('heading_text') - heading_id = match.group('heading_id') - - if heading_id: - heading_id = heading_id.strip() - else: - heading_id = generate_heading_id(heading_text) - - if heading_id == '': - heading_id = None - - heading_tags.append(heading_id) - - if heading_tags: - mrg_entry['headingids'] = heading_tags - - # Replace glossaryText placeholders if it exists - glossary_text = mrg_entry.get('glossaryText') - - if glossary_text: - glossary_text_match = re.findall(r'%%(.*?)\^(.*?)%%', glossary_text) - for match in glossary_text_match: - show_text = match[0] - ref_text = match[1] - placeholder = f"%%{show_text}^{ref_text}%%" - replacement = f"[{show_text}](@)" - glossary_text = glossary_text.replace(placeholder, replacement) - mrg_entry['glossaryText'] = glossary_text - - # Replace hoverText placeholders if it exists - hover_text = mrg_entry.get('hoverText') - - if hover_text: - def capitalize_first_letters(match): - text = match.group(1) - words = text.split() - capitalized_words = [word.capitalize() if word.islower() else word for word in words] - return ' '.join(capitalized_words) - - hover_text = re.sub(r'\[([^\]]+?)\]\(.*?@[^@]*\)', capitalize_first_letters, hover_text) - - mrg_entry['hoverText'] = hover_text - - return mrg_entry - -def generate_heading_id(heading_text): - generated_id = heading_text.lower() - generated_id = re.sub(r'\W+', ' ', generated_id) - generated_id = generated_id.replace(' ', '-') - generated_id = re.sub(r'-{2,}', '-', generated_id) - generated_id = generated_id.strip('-') - if generated_id == '': - return None - return generated_id - -def construct_entries_section(saf_data): - directory = saf_data.get("scope", {}).get("curatedir") - if not directory: - print("Error: 'curatedir' field missing in SAF.yaml.") - return - - if not os.path.exists(directory): - print(f"Error: Directory '{directory}' does not exist.") - return [] - - print(f"Processing files in directory: {directory}") - - markdown_files = glob.glob(os.path.join(directory, '*.md')) - - if not markdown_files: - print(f"Error: No Markdown files found in directory '{directory}'.") - return [] - - mrg_entries = [] - error_messages = [] - - for md_file in markdown_files: - mrg_entry = process_markdown_file(md_file, saf_data, error_messages) - if mrg_entry: - mrg_entries.append(mrg_entry) - - if error_messages: - print("\n".join(error_messages)) - - return mrg_entries - -# Main program - -def main(version_tag=None): - saf_path = os.path.join(os.getcwd(), "SAF.yaml") - if not os.path.exists(saf_path): - print("Error: SAF.yaml file not found.") - return - - with open(saf_path, "r", encoding="utf-8") as saf_file: - saf_data = yaml.safe_load(saf_file) - - if version_tag is None: - version_tag = saf_data.get("scope", {}).get("defaultvsn") - - print(f"Version tag: {version_tag}") - - scope_tag = saf_data.get("scope", {}).get("scopetag", "") - - # Generate YAML filename and path - file_name = f"mrg.{scope_tag}.{version_tag}.yaml" - - # Check if glossarydir exists - glossary_dir = saf_data.get("scope", {}).get("glossarydir", "") - if not os.path.exists(os.path.join(os.getcwd(), glossary_dir)): - print(f"Error: 'glossarydir' directory '{glossary_dir}' does not exist in {os.path.join(os.getcwd())}.") - return - - # Create the full path for the MRG file - file_path = os.path.join(os.getcwd(), glossary_dir, file_name) - - # Generate the contents of the MRG file - mrg_terminology = construct_terminology_section(saf_data, version_tag) - mrg_scopes = construct_scopes_section(saf_data) - mrg_entries = construct_entries_section(saf_data) - - yaml_data = { - "terminology": mrg_terminology, - "scopes": mrg_scopes, - "entries": mrg_entries - } - - ruamel = YAML() - ruamel.indent(mapping=2, sequence=4, offset=2) - ruamel.dump(yaml_data, open(file_path, 'w', encoding='utf-8')) - - print(f"Generated YAML file: {file_path}") - -if __name__ == "__main__": - parser = argparse.ArgumentParser() - parser.add_argument('-v', '--version', help='Version tag', default=None) - args = parser.parse_args() - - main(version_tag=args.version) diff --git a/docs/terminology-design/overview.md b/docs/terminology-design/overview.md deleted file mode 100644 index 32e7c91a16..0000000000 --- a/docs/terminology-design/overview.md +++ /dev/null @@ -1,71 +0,0 @@ ---- -id: overview -// hide_table_of_contents: true -// displayed_sidebar: terminologyDesignSideBar -date: 20221020 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -# On the Design of Terminology - -This page is under construction - -In order for a [community](@) (e.g. a workgroup, taskforce, project/product team, department, etc.) to realize its [objectives](@), it is beneficial that its members -1. have **a [common understanding](@)** of the ideas, [concepts](@) and other [knowledge artifacts](@)[^1] that are relevant for realizing these [objectives](@), -2. are **a [linguistic unity](@)**, i.e. they use the same [terms](@) to represent these ideas and [concepts](@), and -3. are able to provide themselves with **assurances** that everyone consistently and consequently uses the same [term](@) for the same [concept](@). - -[^1]: ideas, [concepts](@) and other [knowledge artifacts](@) are (intangible) parts of a [knowledge](@). One could say that they constitute 'the mind' of [parties](@). They need a (tangible) representation, e.g. [terms](@), figures, sounds, etc. that [parties](@) can use to communicate with each other. The problem is that each participant of a [community](@) must be sufficiently sure that not only they all use the same [terms](@), but also that they have a [common understanding](@) of the actual [concept](@) that an individual [term](@) represents. - -These three elements form the basis of cooperation. They do not imply that the members of the [community](@) agree about everything, but it does mean that they have a solid foundation for formulating and discussing ideas, arguments, etc. They are a means to mitigate the risks (and associated costs) of misunderstandings, primarily by preventing such risks to materialize. - -Note that preventing misunderstandings is not always a good idea. Many jokes, comedies etc. are based on misunderstandings occurring. Also, there are many situations in which the risks of misunderstandings aren't so high to warrant putting effort in preventing them, such as social talks at a coffee machine. - -Our focus is on contexts in which misunderstandings _do_ have consequences that are serious enough to warrant spending time, effort and resources in creating a [common understanding](@), a [linguistic unity](@), and providing the assurances that this is all actually the case. - -[TL;DR](https://www.urbandictionary.com/define.php?term=tl%3Bdr): In the subsequent sections we will: -- illustrate the importance of realizing a [common understanding](@), -- elaborate on the difficulties that people encounter as they try to do so, -- propose a new approach that aims to overcome such difficulties and realize a provable [common understanding](@). - -## The importance of 'linguistic unity' - -[Many cultures](https://en.wikipedia.org/wiki/Tower_of_Babel#Comparable_myths) have stories, similar to that of the [Tower of Babel](https://en.wikipedia.org/wiki/Tower_of_Babel), that observe that the big feats, such as building a "tower, whose top may reach unto heaven", cannot be achieved unless the people that do this have a [linguistic unity](@), i.e. they use [terms](@) that they all understand in the same way. For example, if two railway companies have no [linguistic unity](@), they may have different ideas associated with the [term](@) [track gauge](https://en.wikipedia.org/wiki/Track_gauge), which results in a risk that trains cannot run on one of the company's track. - -The architecture of the building of the EU parliament in Strasbourg intentionally resembles the Tower of Babel as painted by Bruegel (see Figure 1), as a constant reminder a [common understanding](@) and a [linguistic unity](@) are required in order for them to (dis)agree. - -

-EU Parliament building resembles Tower of Babel by BruegelFigure 1. The EU Parliament building resembles the Tower of Babel by Bruegel -

- -## The difficulty of realizing linguistic unity - -Many people that have been part of project teams that engage in large projects have experienced this in person, and can tell many stories about how gaining a workable [linguistic unity](@) wasn't really achieved in some project, even though project members all agreed on how important this is, and real attempts were made to realize it. - -The most common approach for this is to create a [glossary](https://www.merriam-webster.com/dictionary/glossary), i.e. an alphabetically sorted list of terms and their descriptions (sometimes also called [definitions](https://www.merriam-webster.com/dictionary/definition)), that the participants in a project all agree on. Usually, this means that people start to collect terms and descriptions that they either make up, or copy from other existing glossaries. Then, discussions follow that typically result in the modification of descriptions, as well as in more discussions. At some point, the effort needs to stop, and the glossary is established (published, finalized). - -A glossary that has been created this way typically does not establish the [linguistic unity](@) that was attempted to be realized. If it had, you would not find documents (articles, blogs, mailing list messages, github issues, etc.) that used a term in a meaning that differs from the meaning as defined in the glossary they supposedly use. Also, you would not see discussions between people that each use a specific term in their own way, i.e. in a meaning that differs from that of the other persons. - -:::info Editor's note -We need some additional text here that on the one hand acknowledges the genuine efforts of people to achieve [linguistic unity](@), and explains why these efforts so seldomly result in the intended effects. - -Also, perhaps, some texts that comment on the quality (i.e.: usefulness) of definitions, e.g.: -- terms that are defined in terms of themselves; -- terms that are followed by a description of which it is unclear how that defines a term; -- terms that are specified as a criterion so that people can determine what is (not) an instance (example) of the term; -- terms that are specified such that, when a sentence mentions a term, and the term is replaced with its definition, the sentence is still grammatically correct and meaningful. -- ... -::: - -## The approach called Terminology Design - -:::info Editor's note -text needs to be written here -::: diff --git a/docs/terminology-design/overview/00-common-understanding.md b/docs/terminology-design/overview/00-common-understanding.md deleted file mode 100644 index d92a101eba..0000000000 --- a/docs/terminology-design/overview/00-common-understanding.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -id: common-understanding -sidebar_label: Understanding One Another -// hide_table_of_contents: true -// displayed_sidebar: terminologyDesignSideBar -date: 20221020 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - - -export const mark = ({children}) => ( - - {children} - ); - -# Enabling a Common Understanding in a Community - -This page is under construction - -In order for a [community](@) (e.g. a workgroup, taskforce, project/product team, department, etc.) to realize its [objectives](@), it is beneficial that its members have a common set of the ideas, [concepts](@) and other [knowledge artifacts](@) that are relevant for realizing these [objectives](@). The ability to realize such a common understanding, and to demonstrate that this is actually the case, is a critical capability for success. - -:::info Editor's note -([Agredo-Delgado, et. al., 2021](https://link.springer.com/article/10.1007/s10588-021-09326-z))[^1] have tested a process for constructing a shared understanding in computer-supported collaborative work, where the construction part consists of 4 steps: -1. each group member acquires an individual understanding of the subject; -2. each group member exposes his/her ideas and the others actively listen to them; -3. the group refines, builds or modifies the original ideas; -4. the differences of interpretation between the group members are dealt with in a constructive fashion, through arguments and clarifications. -::: - -[^1]: Agredo-Delgado, V., Ruiz, P.H., Mon, A. et al. Applying a process for the shared understanding construction in computer-supported collaborative work: an experiment. Comput Math Organ Theory 28, 247-270 (2022). https://doi.org/10.1007/s10588-021-09326-z diff --git a/docs/terminology-design/overview/10-purpose.md b/docs/terminology-design/overview/10-purpose.md deleted file mode 100644 index 71d58d6480..0000000000 --- a/docs/terminology-design/overview/10-purpose.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -id: purpose -// sidebar_label: Why Design a Terminology -// hide_table_of_contents: true -// displayed_sidebar: terminologyDesignSideBar -date: 20221020 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -# Why _Design_ a Terminology - -This page is under construction - -export const mark = ({children}) => ( - - {children} - ); diff --git a/docs/terminology-design/overview/20-design-principles.md b/docs/terminology-design/overview/20-design-principles.md deleted file mode 100644 index cd9d7fd725..0000000000 --- a/docs/terminology-design/overview/20-design-principles.md +++ /dev/null @@ -1,18 +0,0 @@ ---- -id: design-principles -// sidebar_label: Design Principles -// hide_table_of_contents: true -// displayed_sidebar: terminologyDesignSideBar -date: 20221020 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -# Design Principles - -This page is under construction - -## Summary diff --git a/docs/terminology-design/saf.yaml b/docs/terminology-design/saf.yaml deleted file mode 100644 index 64a7493e29..0000000000 --- a/docs/terminology-design/saf.yaml +++ /dev/null @@ -1,44 +0,0 @@ -# -# This is a Scope Administration File that can be used in conjunction with [Terminology Engine v2](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2/tev2-overview). -# -# The first section defines meta-data concerning the scope itself, both for technical use and human use. -# It shows where directories and files live that ar part of the scope, and also -# ways in which people can contribute, raise issues, see what's going on, discuss, etc. -# -scope: - scopetag: termdsn # identifier that curators have determined for this terminology - scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/terminology-design # URL of the scope-directory - curatedir: terms # directory where all curated files are located. Full URL is `scopedir`/`curatedir` - glossarydir: glossaries # directory where all glossary files and GDFs are located. Full URL is `scopedir`/`glossarydir` - defaultvsn: latest # vsntag that identifies the default terminology. MRG is located at `scopedir`/`glossarydir`/mrg.`scopetag`.`defaultvsn`.yaml - license: LICENSE.md # file that contains the (default) licensing conditions. Full URL is `scopedir`/`license` - statuses: [ proposed, approved, deprecated ] # list of status tags that are defined for terminological artifacts in this scope - issues: https://github.com/tno-terminology-design/tev2-specifications/issues # URL where issues can be raised and handled - website: https://tno-terminology-design.github.io/tev2-specifications/docs/terminology-design # base URL for creating links to rendered versions of Curated Texts. It should also serve as the home page of the Tterminology. - curators: # contacting individual curators - - name: RieksJ - email: # we split up the email address to reduce the likelihood of the address being harvested for spamming - id: rieks.joosten - at: tno.nl -# -# The second section contains a mapping between scopetags that are used within the scope, and the associated scopedirs. -# This enables tools to find the [SAF](@) of these [scopes](@), and from there all other directories, files etc. -# that live within them, e.g. to use/import their data. -# -scopes: # -- scopetag: tev2 - scopedir: https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/tev2 -- scopetag: essiflab - scopedir: https://github.com/tno-terminology-design/tev2-specifications/docs/terminology-design/tree/master/docs -- scopetag: ctwg - scopedir: https://github.com/trustoverip/ctwg -# -# The third section specifies the versions that are actively maintained by the curators. -# For each version, the set of terms is selected that constitute the terminology. -# See the Glossary Generation Tool (GGT) for details about the syntax and semantics. -# -versions: -- vsntag: v0.1 - altvsntags: [ latest ] - termselcrit: - - "*@tev2" # import all tev2 terms. \ No newline at end of file diff --git a/docs/terminology-design/terms/.concept-file.md b/docs/terminology-design/terms/.concept-file.md deleted file mode 100644 index a81eae7b36..0000000000 --- a/docs/terminology-design/terms/.concept-file.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -# TEv2 Curated Text Header -term: {nameOfNewConcept} -termType: concept -isa: {ConceptOfWhichThisConceptIsASpecialization} -glossaryTerm: "{Text that is used for the term in a human readable glossary.}" -glossaryText: "{text that appears in the glossary entry for this term. It may contain [termRefs](@)}." -synonymOf: -grouptags: -formPhrases: {nameOfNewConcept}{ss} -# Curation status -status: proposed -created: 2022-06-06 -updated: 2022-06-06 -# Origins/Acknowledgements -contributors: {yourNameOrSomethingSimilar} -attribution: "[name of attribution site](https://link-to-attribution-site)" -originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" -# TRRT elements -hoverText: "{text that appears as a popup when the term is referenced on a website}" ---- - -# {nameOfNewConcept} (or: {glossaryTerm}) - -import useBaseUrl from '@docusaurus/useBaseUrl' -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; -export const mark = ({children}) => ( {children} ); - - - -## Short Description - - -## Purpose - - -## Criteria - - -## Examples - - -## Background - - -## Use-cases - - -## Notes - - - \ No newline at end of file diff --git a/docs/terminology-design/terms/author.md b/docs/terminology-design/terms/author.md deleted file mode 100644 index 10d16c315c..0000000000 --- a/docs/terminology-design/terms/author.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -# TEv2 Curated Text Header -term: author -termType: concept -isa: tev2-role -glossaryTerm: -glossaryText: "A person that creates and maintains texts (documentation, whitepapers, specifications, standards, [curated texts](@), etc.), and while doing so ensures that every [term](@) that it uses and that is defined in the [context](scope@) of that text, is used in the meaning in which that [term](@) is defined." -synonymOf: -grouptags: -formPhrases: author{ss} -# Curation status -status: proposed -created: 2023-01-10 -updated: 2023-01-10 -# Origins/Acknowledgements -contributors: RieksJ -attribution: "[eSSIF-Lab](https://essif-lab.github.io/framework)" -originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" -# TRRT elements -hoverText: "Author: a person that creates and maintains texts (documentation, whitepapers, specifications, standards, Curated-texts, etc.), and while doing so ensures that every [term](@) that it uses and that is defined in the context (Scope) of that text, is used in the meaning in which that [term](@) is defined." ---- - -# Author - -import useBaseUrl from '@docusaurus/useBaseUrl' - -## Short Description -An **Author** is a person that creates and maintains texts (documentation, whitepapers, specifications, standards, [curated texts](@), etc.), and while doing so ensures that every [term](@) that appears in the text and that is defined in the [context](scope@) of that text, is used in the meaning in which that [term](@) is defined. - -Their primary task/responsibility within a [community](@) is to provide actual written content, without having to bother about the 'details' like layout, how it is all rendered (processed to produce human readable artifacts such as static websites, PDFs, whitepapers etc. [Authors](@) are provided the means to mark-up [terms](@) in their texts with a easy to type reference to its meaning ([definition](@)), the effect of which becomes apparent in the rendered artifacts created from that text. These effects, such as popups (in a static website) that show the [definition](@) of the [term](@) used, or an automatically generated [glossary](@) that can be used as an appendix in a paper, makes it easier for [readers](@) to understand what the [author](@) means to convey with the texts (s)he has written. - -[Authors](@) may also identify any specific needs or mechanisms that help them do the aforementioned tasks, and communicate these needs to their [curators](@), or otherwise contribute to the further development of [TEv2](@) so that such needs and mechanisms may be supported. - -## Purpose -For many (but not all) texts, it is important that the people that create and maintain texts make an effort to construct the text in such a way that the intended audience (their [readers](@)) can easily understand the message(s) they try to convey - in an unambiguous way. In the context of [TEv2](@), we use the term '[author](@)' for people that do this, and ensure that [terms](@) that are explicitly [defined](@) are used in their intended meaning. - -## Notes - -- The [Manual for Authoring](/docs/terminology-design/manuals/authoring) provides guidance for [authors](@) that want to become more experienced in writing high-quality texts. diff --git a/docs/terminology-design/terms/common-understanding.md b/docs/terminology-design/terms/common-understanding.md deleted file mode 100644 index de0ba8f683..0000000000 --- a/docs/terminology-design/terms/common-understanding.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -# TEv2 Curated Text Header -term: common-understanding -termType: concept -isa: -glossaryTerm: -glossaryText: "the state of a [community](@) where every member has the same understanding about the meaning of (a) the [terms](@) used in the [community](@), (b) the relations between these [terms](@), and (c) any constraints/rules that apply." -synonymOf: -grouptags: -formPhrases: -# Curation status -status: proposed -created: 2022-10-26 -updated: 2022-10-26 -# Origins/Acknowledgements -contributors: RieksJ -attribution: "[eSSIF-Lab](https://essif-lab.github.io/framework)" -originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" ---- - -# Common Understanding - -:::caution -The entire section on Terminology Design is still under construction.
-::: - -## Summary -A **common understanding** is the state of a [community](@) where every member has the same understanding about the meaning of -1. the [terms](@) used in the [community](@), -2. the relations between these [terms](@), and -3. any constraints/rules that apply. - -The latter two items are crucial for a [common understanding](@); they are prerequisite for having coherent and consistent ways of thinking/reasoning (similar as being a [linguistic unity](@) is). - -It is a common mistake to confuse the [concepts](@) called '[common understanding](@)' and '[linguistic unity](@)'.[^1] It takes an active commitment of members of the [community](@) to consistently (and correctly) use the [terms](@) from the [glossary](@), in their intended (and documented) meanings. that isn't easy to achieve.[^2] - -[^1]: For example, the W3C Recommendation "[Verifiable Credentials Data Model v1.1](https://www.w3.org/TR/vc-data-model/)" has a section on terminology, that says that [verification](https://www.w3.org/TR/vc-data-model/#dfn-verify) is "The evaluation of whether a verifiable credential or verifiable presentation is an authentic and timely statement of the issuer or presenter, respectively". Yet, the second (green) note in [Section 5.7 Evidence](https://www.w3.org/TR/vc-data-model/#evidence) says "This driver's license was used in the issuance process to verify that "Example University" ***verified the subject***". According to the definition, verification is not about subjects. But even if subjects could be verified, it is hard to fathom that this would imply that a subject is a statement, or that it could be evaluated of whether (or not) it is an authentic and timely statement. - -[^2]: In the Github [repository](https://github.com/w3c/vc-data-model) where the W3C Recommendation "[Verifiable Credentials Data Model v1.1 (VCDM)](https://www.w3.org/TR/vc-data-model/)" is being developed, it is relatively easy to find issues in which contributors express themselves using terms that are defined in the VCDM, but in another meaning. A notorious example is the phrase "subject of a (verifiable) credential". Issues such as [#226](https://github.com/w3c/vc-data-model/issues/226) used this phrase, and [an issue (#464)](https://github.com/w3c/vc-data-model/issues/464) was raised, resulting in appropriate changes in the VCDM. Nevertheless, the practice continued, e.g. in the title of [issue #792](https://github.com/w3c/vc-data-model/issues/792), in a comment on [issue #875](https://github.com/w3c/vc-data-model/issues/875#issuecomment-1125039624), resulting in raising [issue #957](https://github.com/w3c/vc-data-model/issues/957), which calls for more clarification of the VCDM texts. - -A [community](@) that wants to obtain/maintain a [common understanding](@) should have ways to test whether or not this is the case. - -:::info Editor's note -We need to say that this is what 'terminology design' is about, and point to the methods for testing this. -::: - - -## Purpose -Having a [common understanding](@) is one of the prerequisites of efficiently and effectively working together. - -## Criteria -A **common understanding** the state of a [community](@) where every member has the same understanding about the meaning of (a) the [terms](@) used in the [community](@), (b) the relations between these [terms](@), and (c) any constraints/rules that apply. diff --git a/docs/terminology-design/terms/domain-expert.md b/docs/terminology-design/terms/domain-expert.md deleted file mode 100644 index 3293bbd36c..0000000000 --- a/docs/terminology-design/terms/domain-expert.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -# TEv2 Curated Text Header -term: domain-expert -termType: concept -isa: -glossaryTerm: -glossaryText: "a person that has expert [knowledge](@) about a specific topic (subject matter), or skills in a particular area (domain)." -synonymOf: subject-matter-expert -grouptags: -formPhrases: domain-expert{ss}, subject-matter-expert{ss} -# Curation status -status: proposed -created: 2022-11-23 -updated: 2022-11-23 -# Origins/Acknowledgements -contributors: RieksJ -attribution: "[eSSIF-Lab](https://essif-lab.github.io/framework)" -originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" ---- - -# Domain Expert (or Subject Matter Expert) - -:::caution -The entire section on Terminology Design is still under construction.
-::: - -## Summary -A **domain expert** or **subject matter expert** is a person that has expert [knowledge](@) about a specific topic (subject matter), or skills in a particular area (domain). Their knowledge and skills are instrumental, e.g., in the design and development of architectures, information or production processes, and in the specifications of systems, components or other artifacts. - -A common assumption is that [domain experts](@) are capable of expressing the [knowledge](@) that they can prove they have. Under this assumption, it is logical to expect that [domain experts](@) are capable to author e.g., the specifications of an IT system that is complete, consistent, coherent, correct, clear and concise. As this assumption is actually a misconception[^1], such expectations inevitably lead to problems.[^2] - -## Purpose -The purpose of having **domain experts** and **subject matter experts** make (or contribute to the creation of) certain artifacts, such as an architecture, an information or production process, the specifications of a system (component), etc., is that their knowledge and skills reduce the [risk](@) of the artifact not being fit-for-purpose. - -## Criteria -A **domain expert** or **subject matter expert** is a person that has expert [knowledge](@) about a specific topic (subject matter), or skills in a particular area (domain). - -## Notes - -[^1]: People that are native speakers of a language, can usually demonstrate their knowledge of the specifications of that language (its grammar), by showing that they can (1) determine whether or not a sentence in that language is grammatically correct, (2) correct the sentences that were incorrect and (3) come up with (say) 5 alternatives for correcting an incorrect sentence, and picking out 'the most beautiful', or 'the best' one. However, when asked whether they could write down the specifications such that the result is consistent, coherent, complete, cogent, congruent - and other c-words that refer to characteristics that specifications are typically expected to have, they will say 'no'. Even worse: if they are presented a booklet that is about the grammar of their mother's tongue, and are asked to determine whether or not it specifies that grammar in a consistent, coherent, complete, etc. way, they will also decline. - -[^2]: A (temporary) parliamentary committee in the Netherlands conducted research into government ICT projects (July 2012 - October 2014). It had to map out the achieved and missed social effects due to the lack of proper information provision in government ICT projects. They observed that in many cases, specifications did not meet the requirements of being complete, consistent, correct, etc., which is one of the causes that the government spent between 1-5 billion euro more than it would have needed to. diff --git a/docs/terminology-design/terms/linguistic-unity.md b/docs/terminology-design/terms/linguistic-unity.md deleted file mode 100644 index 71372f2d09..0000000000 --- a/docs/terminology-design/terms/linguistic-unity.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -# TEv2 Curated Text Header -term: linguistic-unity -termType: concept -isa: -glossaryTerm: -glossaryText: "the property of a [community](@) of having a [terminology](@) (language) that every member of the [community](@) uses." -synonymOf: -grouptags: -formPhrases: -# Curation status -status: proposed -created: 2022-10-26 -updated: 2022-10-26 -# Origins/Acknowledgements -contributors: RieksJ -attribution: "[eSSIF-Lab](https://essif-lab.github.io/framework)" -originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" ---- - -# Linguistic Unity - -:::caution -The entire section on Terminology Design is still under construction.
-::: - -## Summary -We say that a [community](@) has the property of being a **linguistic unity** if there is a single [terminology](@) (language) that every member of the [community](@) uses. - -The mere existence of a [glossary](@) that is developed (and perhaps also maintained) in a [community](@) is not a sure sign a [linguistic unity](@). Different members in a [community](@) that has developed a [glossary](@) may keep using their own preferred [terms](@). If this is done in documentation, readers may get confused because - -:::info Editor's note -examples of the aforementioned statement are needed/should be added, e.g. as a footnote -::: - -Being a [linguistic unity](@) does not mean, however, that people have a [common understanding](@): members of the [community](@) may use the same words, but still assign them with different meaning ([semantics](@)). - -## Purpose -Having a [terminology](@) that every member of a [community](@) uses in the same way/meaning is one of the prerequisites for efficiently and effectively working together. - -## Criteria -A [community](@) has the property of being (or: is) a **linguistic unity** if there is (at least) one [terminology](@), the [terms](@) of which are used by every member of that [community](@). diff --git a/docs/terminology-design/terms/@.md b/docs/terms/@.md similarity index 100% rename from docs/terminology-design/terms/@.md rename to docs/terms/@.md diff --git a/docs/tev2/terms/_{termid}.mdx b/docs/terms/_{termid}.mdx similarity index 99% rename from docs/tev2/terms/_{termid}.mdx rename to docs/terms/_{termid}.mdx index a0013e65de..65b7c27d55 100644 --- a/docs/tev2/terms/_{termid}.mdx +++ b/docs/terms/_{termid}.mdx @@ -20,7 +20,7 @@ created: {today's date} updated: {today's date} # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/author.md b/docs/terms/author.md similarity index 98% rename from docs/tev2/terms/author.md rename to docs/terms/author.md index 9e623890e5..46c057db70 100644 --- a/docs/tev2/terms/author.md +++ b/docs/terms/author.md @@ -17,7 +17,7 @@ created: 20230723 updated: 20230723 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/body.md b/docs/terms/body.md similarity index 97% rename from docs/tev2/terms/body.md rename to docs/terms/body.md index de1fa1b667..7026c91672 100644 --- a/docs/tev2/terms/body.md +++ b/docs/terms/body.md @@ -17,7 +17,7 @@ created: 20230723 updated: 20230723 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/concept.md b/docs/terms/concept.md similarity index 100% rename from docs/tev2/terms/concept.md rename to docs/terms/concept.md diff --git a/docs/tev2/terms/conceptualization.md b/docs/terms/conceptualization.md similarity index 98% rename from docs/tev2/terms/conceptualization.md rename to docs/terms/conceptualization.md index 81588163f4..d30c1cc62c 100644 --- a/docs/tev2/terms/conceptualization.md +++ b/docs/terms/conceptualization.md @@ -17,7 +17,7 @@ created: 20230723 updated: 20230723 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/converter.md b/docs/terms/converter.md similarity index 96% rename from docs/tev2/terms/converter.md rename to docs/terms/converter.md index f4984b7d89..2112b27714 100644 --- a/docs/tev2/terms/converter.md +++ b/docs/terms/converter.md @@ -17,7 +17,7 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/corpus.md b/docs/terms/corpus.md similarity index 100% rename from docs/tev2/terms/corpus.md rename to docs/terms/corpus.md diff --git a/docs/tev2/terms/curate.md b/docs/terms/curate.md similarity index 97% rename from docs/tev2/terms/curate.md rename to docs/terms/curate.md index aac6ebca61..516063fd9b 100644 --- a/docs/tev2/terms/curate.md +++ b/docs/terms/curate.md @@ -17,7 +17,7 @@ created: 20230723 updated: 20230723 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/curated-text.md b/docs/terms/curated-text.md similarity index 91% rename from docs/tev2/terms/curated-text.md rename to docs/terms/curated-text.md index 65a438a073..7a4a13f130 100644 --- a/docs/tev2/terms/curated-text.md +++ b/docs/terms/curated-text.md @@ -24,9 +24,9 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? A **[curated text](@)** is a text that documents a [concept](@) or other [knowledge artifact](@) of a specific [community](@) or other [party](@), and is located within a [scope](@) that is owned by that [community](@)/[party](@). A large variety of traits can be documented, such as the [(scoped) term](@) that is used within the [scope](@) to represent the [artifact](knowledge-artifact@), a [definition](@), explanatory texts, examples, etc., etc.; anything that helps others understand the intricacy of these [artifacts](@). -The (technical) structure and syntax for [curated texts](@) is specified [here](/docs/tev2/spec-files/ctext). +The (technical) structure and syntax for [curated texts](@) is specified [here](/docs/spec-files/ctext). -The manuals for [contributors](/docs/tev2/manuals/contributor), [authors](/docs/tev2/manuals/[author](@)) and [curators](/docs/tev2/manuals/curator) will provide guidance for people that act in these respective roles as they work with [curated texts](@). +The manuals for [contributors](/docs/manuals/contributor), [authors](/docs/manuals/[author](@)) and [curators](/docs/manuals/curator) will provide guidance for people that act in these respective roles as they work with [curated texts](@). :::info Editor's Note Text needs to be revised from here onward. Here are some ideas to mention: diff --git a/docs/tev2/terms/curatedir.md b/docs/terms/curatedir.md similarity index 100% rename from docs/tev2/terms/curatedir.md rename to docs/terms/curatedir.md diff --git a/docs/tev2/terms/curator.md b/docs/terms/curator.md similarity index 98% rename from docs/tev2/terms/curator.md rename to docs/terms/curator.md index 810a91454a..0cc54c41cc 100644 --- a/docs/tev2/terms/curator.md +++ b/docs/terms/curator.md @@ -17,7 +17,7 @@ created: 20230723 updated: 20230723 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/define.md b/docs/terms/define.md similarity index 98% rename from docs/tev2/terms/define.md rename to docs/terms/define.md index 46dbe423e8..a5bff56704 100644 --- a/docs/tev2/terms/define.md +++ b/docs/terms/define.md @@ -17,7 +17,7 @@ created: 20230723 updated: 20230723 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/definition.md b/docs/terms/definition.md similarity index 100% rename from docs/tev2/terms/definition.md rename to docs/terms/definition.md diff --git a/docs/tev2/terms/dictionary.md b/docs/terms/dictionary.md similarity index 100% rename from docs/tev2/terms/dictionary.md rename to docs/terms/dictionary.md diff --git a/docs/tev2/terms/formatted-text.md b/docs/terms/formatted-text.md similarity index 98% rename from docs/tev2/terms/formatted-text.md rename to docs/terms/formatted-text.md index 4fc54b7d74..0592d665c1 100644 --- a/docs/tev2/terms/formatted-text.md +++ b/docs/terms/formatted-text.md @@ -17,7 +17,7 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/formphrase.md b/docs/terms/formphrase.md similarity index 97% rename from docs/tev2/terms/formphrase.md rename to docs/terms/formphrase.md index 8be06bdcc4..a97906273e 100644 --- a/docs/tev2/terms/formphrase.md +++ b/docs/terms/formphrase.md @@ -15,7 +15,7 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- @@ -23,7 +23,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? A **Form Phrase** is a word or phrase, other than the actual [term](@) that, when used in a [TermRef](@) would typically also refer to this [term](@). Form phrases may include plural forms, possessive extensions, verb-conjugation forms, and other variations. -Form phrases of a [term](@) can be specified in the [header](@) of the [curated text](@) that describes this [term](@) (in the `formPhrases` field). See the [form-phrase specifications](/docs/tev2/spec-syntax/form-phrase-syntax). +Form phrases of a [term](@) can be specified in the [header](@) of the [curated text](@) that describes this [term](@) (in the `formPhrases` field). See the [form-phrase specifications](/docs/spec-syntax/form-phrase-syntax). ## Examples diff --git a/docs/tev2/terms/glossary.md b/docs/terms/glossary.md similarity index 100% rename from docs/tev2/terms/glossary.md rename to docs/terms/glossary.md diff --git a/docs/tev2/terms/glossarydir.md b/docs/terms/glossarydir.md similarity index 100% rename from docs/tev2/terms/glossarydir.md rename to docs/terms/glossarydir.md diff --git a/docs/tev2/terms/grouptag.md b/docs/terms/grouptag.md similarity index 100% rename from docs/tev2/terms/grouptag.md rename to docs/terms/grouptag.md diff --git a/docs/tev2/terms/header.md b/docs/terms/header.md similarity index 98% rename from docs/tev2/terms/header.md rename to docs/terms/header.md index e465584993..c336b954cf 100644 --- a/docs/tev2/terms/header.md +++ b/docs/terms/header.md @@ -17,7 +17,7 @@ created: 20230723 updated: 20230723 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/hrd.md b/docs/terms/hrd.md similarity index 96% rename from docs/tev2/terms/hrd.md rename to docs/terms/hrd.md index 41840587d7..422ba71d3c 100644 --- a/docs/tev2/terms/hrd.md +++ b/docs/terms/hrd.md @@ -17,7 +17,7 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/hrdt.md b/docs/terms/hrdt.md similarity index 93% rename from docs/tev2/terms/hrdt.md rename to docs/terms/hrdt.md index a691f7066e..21778d3f1a 100644 --- a/docs/tev2/terms/hrdt.md +++ b/docs/terms/hrdt.md @@ -17,7 +17,7 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- @@ -25,4 +25,4 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? **HRDT** stands for **Human Readable Dictionary Tool**. It refers to a software tool designed to create, manage, and process [Human Readable Dictionaries (HRDs)](hrd@). -The [TEv2](@) specifications (will) have a [HRDT specification](/docs/tev2/spec-tools/hrdt) \ No newline at end of file +The [TEv2](@) specifications (will) have a [HRDT specification](/docs/spec-tools/hrdt) \ No newline at end of file diff --git a/docs/tev2/terms/hrg-entry.md b/docs/terms/hrg-entry.md similarity index 86% rename from docs/tev2/terms/hrg-entry.md rename to docs/terms/hrg-entry.md index b0a4d8b070..8d86c9adba 100644 --- a/docs/tev2/terms/hrg-entry.md +++ b/docs/terms/hrg-entry.md @@ -17,7 +17,7 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- @@ -25,11 +25,11 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? An **HRG Entry** is a specific kind of (human-readable) rendering of the combination of a [term](@) and a means that helps readers to understand the meaning of that [term](@) when it is used in a sentence. -The way in which a [term](@) is rendered depends on how the [HRGT](@) is called. Specifically, a [term](@) that is defined as a `synonymOf` another [term](@) may be rendered in a way that differs from the way in which [terms](@) are rendered that are not a `synonymOf` some other [term](@). Details are provided in the [HRGT specs](/docs/tev2/spec-tools/hrgt). +The way in which a [term](@) is rendered depends on how the [HRGT](@) is called. Specifically, a [term](@) that is defined as a `synonymOf` another [term](@) may be rendered in a way that differs from the way in which [terms](@) are rendered that are not a `synonymOf` some other [term](@). Details are provided in the [HRGT specs](/docs/spec-tools/hrgt). The [terminology pattern](pattern-terminology@) provides an overview of how this concept fits in with related concepts. -The [HRGT specs](/docs/tev2/spec-tools/hrgt) document how [HRG entries](@) are selected (and manipulated) for the construction of a particular [HRG](@). They also document how [terms](@) are rendered that are, and those that are not [synonyms](@) of some other [term](@) (there may be differences between them). +The [HRGT specs](/docs/spec-tools/hrgt) document how [HRG entries](@) are selected (and manipulated) for the construction of a particular [HRG](@). They also document how [terms](@) are rendered that are, and those that are not [synonyms](@) of some other [term](@) (there may be differences between them). ### Purpose diff --git a/docs/tev2/terms/hrg.md b/docs/terms/hrg.md similarity index 96% rename from docs/tev2/terms/hrg.md rename to docs/terms/hrg.md index c72b1c80b5..b6afc0b92c 100644 --- a/docs/tev2/terms/hrg.md +++ b/docs/terms/hrg.md @@ -17,7 +17,7 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/hrgt.md b/docs/terms/hrgt.md similarity index 65% rename from docs/tev2/terms/hrgt.md rename to docs/terms/hrgt.md index 38c659499b..ca6b48fcf4 100644 --- a/docs/tev2/terms/hrgt.md +++ b/docs/terms/hrgt.md @@ -6,7 +6,7 @@ term: hrgt termType: concept isa: tool glossaryTerm: Human Readable Glossary Tool (HRGT) -glossaryText: "a software tool designed to create, manage, and process [Human Readable Glossaries (HRGs)](@), as [specified by TEv2](/docs/tev2/spec-tools/hrgt). HRGTs offer features for selecting [terms](@) that are [curated](@) within the [scope](@) it is run in, or from other [scopes](@)." +glossaryText: "a software tool designed to create, manage, and process [Human Readable Glossaries (HRGs)](@), as [specified by TEv2](/docs/spec-tools/hrgt). HRGTs offer features for selecting [terms](@) that are [curated](@) within the [scope](@) it is run in, or from other [scopes](@)." hoverText: "HRGT: {(noRef {glossaryText})}" synonymOf: human-readable-glossary-tool grouptags: tools, glossary-tools @@ -17,13 +17,13 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- # HRGT - Human Readable Glossary Tool -**HRGT** stands for **Human Readable Glossary Tool**. It is a software tool designed to create, manage, and process [Human Readable Glossaries (HRGs)](@), as [specified by TEv2](/docs/tev2/spec-tools/hrgt). HRGTs offer features for selecting [terms](@) that are [curated](@) within the [scope](@) it is run in, or from other [scopes](@). +**HRGT** stands for **Human Readable Glossary Tool**. It is a software tool designed to create, manage, and process [Human Readable Glossaries (HRGs)](@), as [specified by TEv2](/docs/spec-tools/hrgt). HRGTs offer features for selecting [terms](@) that are [curated](@) within the [scope](@) it is run in, or from other [scopes](@). -The [TEv2](@) has an [ICT-specification](/docs/tev2/spec-tools/hrgt). +The [TEv2](@) has an [ICT-specification](/docs/spec-tools/hrgt). diff --git a/docs/tev2/terms/ict.md b/docs/terms/ict.md similarity index 76% rename from docs/tev2/terms/ict.md rename to docs/terms/ict.md index 69ae5c2dea..581f03d923 100644 --- a/docs/tev2/terms/ict.md +++ b/docs/terms/ict.md @@ -6,7 +6,7 @@ term: ict termType: acronym isa: tool glossaryTerm: Integrity Checker Tool (ICT) -glossaryText: "a software tool designed to check the integrity and conformity of various files used in the curation and management of [glossaries](@), [dictionaries](@), [curated texts](@), and other data within a terminology project. The ICT verifies that the files adhere to the [TEv2 file specifications](/docs/tev2/tev2-spec-files), ensuring the consistency and accuracy of the terminology data." +glossaryText: "a software tool designed to check the integrity and conformity of various files used in the curation and management of [glossaries](@), [dictionaries](@), [curated texts](@), and other data within a terminology project. The ICT verifies that the files adhere to the [TEv2 file specifications](/docs-spec-files), ensuring the consistency and accuracy of the terminology data." hoverText: "Integrity Checker Tool (ICT): {(noRef {glossaryText})}" synonymOf: integrity-checker grouptags: tools, quality-assurance @@ -17,12 +17,12 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- # Integrity Checker Tool (ICT) -**ICT** stands for **Integrity Checker Tool**. It is a software tool designed to check the integrity and conformity of various files used in the curation and management of [glossaries](@), [dictionaries](@), [curated texts](@), and other data within a terminology project. The ICT verifies that the files adhere to the [TEv2 file specifications](/docs/tev2/tev2-spec-files), ensuring the consistency and accuracy of the terminology data. +**ICT** stands for **Integrity Checker Tool**. It is a software tool designed to check the integrity and conformity of various files used in the curation and management of [glossaries](@), [dictionaries](@), [curated texts](@), and other data within a terminology project. The ICT verifies that the files adhere to the [TEv2 file specifications](/docs-spec-files), ensuring the consistency and accuracy of the terminology data. -The [TEv2](@) has an [ICT-specification](/docs/tev2/spec-tools/ict). +The [TEv2](@) has an [ICT-specification](/docs/spec-tools/ict). diff --git a/docs/tev2/terms/identifier.md b/docs/terms/identifier.md similarity index 100% rename from docs/tev2/terms/identifier.md rename to docs/terms/identifier.md diff --git a/docs/tev2/terms/identify.md b/docs/terms/identify.md similarity index 100% rename from docs/tev2/terms/identify.md rename to docs/terms/identify.md diff --git a/docs/tev2/terms/ingestion-process.md b/docs/terms/ingestion-process.md similarity index 87% rename from docs/tev2/terms/ingestion-process.md rename to docs/terms/ingestion-process.md index 218d2f2f2e..bc0701fafb 100644 --- a/docs/tev2/terms/ingestion-process.md +++ b/docs/terms/ingestion-process.md @@ -6,7 +6,7 @@ term: ingestion termType: concept isa: glossaryTerm: Ingestion (Process) -glossaryText: "the process that is run by a [terms-community](@), in which their members suggest, draft, and discuss [definitions](@) ([terms](@) + [criteria](@)) that are relevant for a particular [scope](@), and converting such contributions into [curated texts](@) that accurately document the [concepts](@) and other [terminologic artifacts](@) and that adhere to the [TEv2-specifications](/docs/tev2/spec-files/ctext)." +glossaryText: "the process that is run by a [terms-community](@), in which their members suggest, draft, and discuss [definitions](@) ([terms](@) + [criteria](@)) that are relevant for a particular [scope](@), and converting such contributions into [curated texts](@) that accurately document the [concepts](@) and other [terminologic artifacts](@) and that adhere to the [TEv2-specifications](/docs/spec-files/ctext)." hoverText: "Ingestion Process: {(noRef {glossaryText})}" synonymOf: grouptags: @@ -17,17 +17,17 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- # Ingestion (Process) -**Ingestion** (or the **ingestion process**) is the process that is run by a [terms-community](@), in which their members suggest, draft, and discuss [definitions](@) ([terms](@) + [criteria](@)) that are relevant for a particular [scope](@), and converting such contributions into [curated texts](@) that accurately document the [concepts](@) and other [terminologic artifacts](@) and that adhere to the [TEv2-specifications](/docs/tev2/spec-files/ctext). +**Ingestion** (or the **ingestion process**) is the process that is run by a [terms-community](@), in which their members suggest, draft, and discuss [definitions](@) ([terms](@) + [criteria](@)) that are relevant for a particular [scope](@), and converting such contributions into [curated texts](@) that accurately document the [concepts](@) and other [terminologic artifacts](@) and that adhere to the [TEv2-specifications](/docs/spec-files/ctext). It is typical that some of the members of the [terms-community](@) are the [curators](@) of the [scope](@) for which the [terminology](@) is being suggested, discussed and maintained. -It is also typical that the members make their contributions in various ways, e.g., using wiki-pages, confluence pages, Google Docs, Word docs, etc. It is important that the members of the [terms-community](@) and the [curators](@) find ways to not only decide on what goes into the [terminology](@), but also how to efficiently convert such contributions into [curated texts](@) that comply with the [specifications](/docs/tev2/spec-files/ctext). The [TEv2 architecture](/docs/tev2/overview/tev2-architecture) acknowledges that this may require some specific tools, which is referred to as the 'ingress toolbox'. +It is also typical that the members make their contributions in various ways, e.g., using wiki-pages, confluence pages, Google Docs, Word docs, etc. It is important that the members of the [terms-community](@) and the [curators](@) find ways to not only decide on what goes into the [terminology](@), but also how to efficiently convert such contributions into [curated texts](@) that comply with the [specifications](/docs/spec-files/ctext). The [TEv2 architecture](/docs/overview/tev2-architecture) acknowledges that this may require some specific tools, which is referred to as the 'ingress toolbox'. ## Examples diff --git a/docs/tev2/terms/ingestion-profile.md b/docs/terms/ingestion-profile.md similarity index 91% rename from docs/tev2/terms/ingestion-profile.md rename to docs/terms/ingestion-profile.md index 9cdb655332..f101bb8ab6 100644 --- a/docs/tev2/terms/ingestion-profile.md +++ b/docs/terms/ingestion-profile.md @@ -24,7 +24,7 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? An **[ingestion profile](@)** is the specification of a method by which files that are in a particular place and format (e.g., wiki files) are turned into a [curated text](@). -The manuals for [contributors](/docs/tev2/manuals/contributor), [authors](/docs/tev2/manuals/author) and [curators](/docs/tev2/manuals/curator) will provide guidance for people that act in these respective roles as they work with [curated texts](@). +The manuals for [contributors](/docs/manuals/contributor), [authors](/docs/manuals/author) and [curators](/docs/manuals/curator) will provide guidance for people that act in these respective roles as they work with [curated texts](@). :::info Editor's Note Text needs to be revised. Here are some ideas to mention: diff --git a/docs/tev2/terms/interpreter.md b/docs/terms/interpreter.md similarity index 86% rename from docs/tev2/terms/interpreter.md rename to docs/terms/interpreter.md index 82f3cb18b1..98deb94290 100644 --- a/docs/tev2/terms/interpreter.md +++ b/docs/terms/interpreter.md @@ -17,7 +17,7 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- @@ -25,4 +25,4 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? An **interpreter** is a software component that reads a (source) text of a specific format, such as a wiki-page or JSON file, and produces a set of [moustache variables](@) based on a predefined profile. These [variables](moustache-variables@) represent extracted data or metadata from the source text. -Interpreters are used, e.g., by the [TRRT](@) to find [TermRefs](@) in raw texts, and create a set of [moustache variables](@) from their [specified syntax](/docs/tev2/spec-syntax/term-ref-syntax) (or the [alternative syntax](/docs/tev2/spec-syntax/term-ref-syntax#alternative-syntax)) \ No newline at end of file +Interpreters are used, e.g., by the [TRRT](@) to find [TermRefs](@) in raw texts, and create a set of [moustache variables](@) from their [specified syntax](/docs/spec-syntax/term-ref-syntax) (or the [alternative syntax](/docs/spec-syntax/term-ref-syntax#alternative-syntax)) \ No newline at end of file diff --git a/docs/tev2/terms/knowledge-artifact.md b/docs/terms/knowledge-artifact.md similarity index 100% rename from docs/tev2/terms/knowledge-artifact.md rename to docs/terms/knowledge-artifact.md diff --git a/docs/tev2/terms/mental-model.md b/docs/terms/mental-model.md similarity index 100% rename from docs/tev2/terms/mental-model.md rename to docs/terms/mental-model.md diff --git a/docs/tev2/terms/moustache-variable.md b/docs/terms/moustache-variable.md similarity index 96% rename from docs/tev2/terms/moustache-variable.md rename to docs/terms/moustache-variable.md index 28593277f3..7de0952249 100644 --- a/docs/tev2/terms/moustache-variable.md +++ b/docs/terms/moustache-variable.md @@ -17,7 +17,7 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/mrd.md b/docs/terms/mrd.md similarity index 97% rename from docs/tev2/terms/mrd.md rename to docs/terms/mrd.md index e7605f294e..79c60cc952 100644 --- a/docs/tev2/terms/mrd.md +++ b/docs/terms/mrd.md @@ -17,7 +17,7 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/mrdt.md b/docs/terms/mrdt.md similarity index 93% rename from docs/tev2/terms/mrdt.md rename to docs/terms/mrdt.md index 99c1e8c2a4..fc2abcee48 100644 --- a/docs/tev2/terms/mrdt.md +++ b/docs/terms/mrdt.md @@ -17,7 +17,7 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- @@ -25,4 +25,4 @@ originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/? **MRDT** stands for **Machine Readable Dictionary Tool**. It refers to a software tool designed to create, manage, and process [Machine Readable Dictionaries (MRDs)](mrd@). -The [TEv2](@) specifications (will) have a [MRDT specification](/docs/tev2/spec-tools/mrdt) \ No newline at end of file +The [TEv2](@) specifications (will) have a [MRDT specification](/docs/spec-tools/mrdt) \ No newline at end of file diff --git a/docs/tev2/terms/mrg-entry.md b/docs/terms/mrg-entry.md similarity index 90% rename from docs/tev2/terms/mrg-entry.md rename to docs/terms/mrg-entry.md index fe6fb0b11c..a866b15c71 100644 --- a/docs/tev2/terms/mrg-entry.md +++ b/docs/terms/mrg-entry.md @@ -24,11 +24,11 @@ An **MRG Entry** is a machine-readable (and interpretable) artifact that contain A [terminology](@) can be seen as the collection of [MRG entries](@) that hold all data related to the [terms](scoped-term@) that the [terminology](@) consists of. -The contents of an [MRG entry](@) may vary, depending on the type of [knowledge artifact](@) that it documents. The kinds of data that are common for all [knowledge artifacts](@) are documented [here](http://localhost:3000/docs/tev2/spec-files/mrg#mrg-entries). +The contents of an [MRG entry](@) may vary, depending on the type of [knowledge artifact](@) that it documents. The kinds of data that are common for all [knowledge artifacts](@) are documented [here](http://localhost:3000/docs/spec-files/mrg#mrg-entries). The [terminology pattern](pattern-terminology@) provides an overview of how this concept fits in with related concepts. -The [terminology construction section](/docs/tev2/spec-tools/terminology-construction) describes how [MRG entries](@) are selected (and manipulated) for the construction of a particular [terminology](@). +The [terminology construction section](/docs/spec-tools/terminology-construction) describes how [MRG entries](@) are selected (and manipulated) for the construction of a particular [terminology](@). ### Purpose diff --git a/docs/tev2/terms/mrg-importer.md b/docs/terms/mrg-importer.md similarity index 97% rename from docs/tev2/terms/mrg-importer.md rename to docs/terms/mrg-importer.md index 03944566e9..a8d2db0341 100644 --- a/docs/tev2/terms/mrg-importer.md +++ b/docs/terms/mrg-importer.md @@ -17,7 +17,7 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/mrg.md b/docs/terms/mrg.md similarity index 68% rename from docs/tev2/terms/mrg.md rename to docs/terms/mrg.md index a53884e1e0..27153caff3 100644 --- a/docs/tev2/terms/mrg.md +++ b/docs/terms/mrg.md @@ -6,7 +6,7 @@ term: mrg termType: concept isa: glossary glossaryTerm: Machine Readable Glossary (MRG) -glossaryText: "a [glossary](@) for a particular (version of a) [terminology](@) that is formatted in YAML, according to the [TEv2 MRG specifications](/docs/tev2/spec-files/mrg), to enable automated processing and integration with software systems." +glossaryText: "a [glossary](@) for a particular (version of a) [terminology](@) that is formatted in YAML, according to the [TEv2 MRG specifications](/docs/spec-files/mrg), to enable automated processing and integration with software systems." hoverText: "MRG: {(noRef {glossaryText})}" synonymOf: grouptags: glossaries, data-structures @@ -17,10 +17,10 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- # MRG - Machine Readable Glossary -An **MRG** is a [glossary](@) for a particular (version of a) [terminology](@) that is formatted in YAML, according to the [TEv2 MRG specifications](/docs/tev2/spec-files/mrg), to enable automated processing and integration with software systems. Unlike [dictionaries](@), the [terms](@) in an MRG are not ambiguous and have clear and well-defined [meanings](definition@). +An **MRG** is a [glossary](@) for a particular (version of a) [terminology](@) that is formatted in YAML, according to the [TEv2 MRG specifications](/docs/spec-files/mrg), to enable automated processing and integration with software systems. Unlike [dictionaries](@), the [terms](@) in an MRG are not ambiguous and have clear and well-defined [meanings](definition@). diff --git a/docs/tev2/terms/mrgt.md b/docs/terms/mrgt.md similarity index 65% rename from docs/tev2/terms/mrgt.md rename to docs/terms/mrgt.md index feac89928b..1ed4877368 100644 --- a/docs/tev2/terms/mrgt.md +++ b/docs/terms/mrgt.md @@ -6,7 +6,7 @@ term: mrgt termType: concept isa: tool glossaryTerm: Machine Readable Glossary Tool (MRGT) -glossaryText: "a software tool designed to create, manage, and process [Machine Readable Glossaries (MRGs)](@), as [specified by TEv2](/docs/tev2/spec-tools/mrgt). MRGTs offer features for selecting [terms](@) that are [curated](@) within the [scope](@) it is run in, or from other [scopes](@)." +glossaryText: "a software tool designed to create, manage, and process [Machine Readable Glossaries (MRGs)](@), as [specified by TEv2](/docs/spec-tools/mrgt). MRGTs offer features for selecting [terms](@) that are [curated](@) within the [scope](@) it is run in, or from other [scopes](@)." hoverText: "MRGT: {(noRef {glossaryText})}" synonymOf: machine-readable-glossary-tool grouptags: tools, glossary-tools @@ -17,13 +17,13 @@ created: 2023-07-31 updated: 2023-07-31 # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- # MRGT - Machine Readable Glossary Tool -**MRGT** stands for **Machine Readable Glossary Tool**. It is a software tool designed to create, manage, and process [Machine Readable Glossaries (MRGs)](@), as [specified by TEv2](/docs/tev2/spec-tools/mrgt). MRGTs offer features for selecting [terms](@) that are [curated](@) within the [scope](@) it is run in, or from other [scopes](@). +**MRGT** stands for **Machine Readable Glossary Tool**. It is a software tool designed to create, manage, and process [Machine Readable Glossaries (MRGs)](@), as [specified by TEv2](/docs/spec-tools/mrgt). MRGTs offer features for selecting [terms](@) that are [curated](@) within the [scope](@) it is run in, or from other [scopes](@). -The [TEv2](@) has an [ICT-specification](/docs/tev2/spec-tools/mrgt). +The [TEv2](@) has an [ICT-specification](/docs/spec-tools/mrgt). diff --git a/docs/tev2/terms/patterns/pattern-terminology.md b/docs/terms/patterns/pattern-terminology.md similarity index 85% rename from docs/tev2/terms/patterns/pattern-terminology.md rename to docs/terms/patterns/pattern-terminology.md index 91095d3180..d18e0d624a 100644 --- a/docs/tev2/terms/patterns/pattern-terminology.md +++ b/docs/terms/patterns/pattern-terminology.md @@ -29,7 +29,7 @@ As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', This [mental model](@) aims to serve the following purposes: - enabling members of a [community](@), as well as other [parties](@), to document their understanding of the [concepts](@) and other [knowledge artifacts](@) (e.g., [mental models](@)) that are relevant for their purposes (i.e., realizing their [objectives](@)). -- provide a solid basis for the design and development of a [set of IT tools](/docs/tev2/tev2-overview) that support [communities](@) as they document their [knowledge](@). +- provide a solid basis for the design and development of a [set of IT tools](/docs-overview) that support [communities](@) as they document their [knowledge](@). ### Introduction @@ -43,7 +43,7 @@ Also, this [management](@) may cause reference documents to be created and maint 2. the terminology-related part. This is where [concepts](@), [definitions](@), [terms](@), [glossaries](@) etc. live. This part is what one needs to create tools/support for managing and maintaining a [terminology](@). Here, we have [concepts](@) with their [definitions](@) and [terms](@) as a means to refer to either. A [concept](@), its [definition](@) live in the same [scope](@), and within that [scope](@) there must be a [term](@) to refer to that [concept](@) and its [definition](@). Within a specific [scope](@), every [term](@) is associated with precisely one such [concept](@) and [definition](@). However, within a [scope](@), a [concept](@)/[definition](@) pair may be referred to by multiple [terms](@), which are then synonyms or aliases of each other. ### Formalized model -Here is a visual representation of this pattern, using the following **[notations and conventions](/docs/tev2/notations-and-conventions#pattern-diagram-notations)**: +Here is a visual representation of this pattern, using the following **[notations and conventions](/docs/notations-and-conventions#pattern-diagram-notations)**: Conceptual model of the 'pattern-terminology' pattern -The main objective of [TEv2](@) is to provide support to [communities](@) that actively seek to [understand one another](/docs/tev2/overview/tev2-purpose), first within the [community](@) itself, but also across [communities](@) that also use [TEv2](@). +The main objective of [TEv2](@) is to provide support to [communities](@) that actively seek to [understand one another](/docs/overview/tev2-purpose), first within the [community](@) itself, but also across [communities](@) that also use [TEv2](@). In practice, this means that [TEv2](@) provides tools and mechanisms that: 1. help [readers](@) of publications (that were generated with [TEv2](@) tools) to understand the [terms](@) that are used therein, in the way that the [authors](@) have intended (rather than interpreting such [terms](@) in their own way); 2. facilitating [authors](@) to write and publish texts where terms can be referenced to their intended meaning, within, and across [scopes](@); 3. supporting [authors](@), [readers](@) and other stakeholders to such publications as they seek to create and further develop a [terminology](@) that they can commit to (within a specific [scope](@)), which we expect to also help develop insights in their subject matter of that [scope](@)). -These contributions are what so-called [curators](@) of the [scope](@) seek to deliver. They are the ones that make sure that there is a [location](scopedir@) where people can contribute to the development of the [terminology](@) of a [scope](@), and tools are installed and operational that enable [authors](@) to use them as they publish their documents. [Curators](@) have their own [manual](/docs/tev2/manuals/curator). +These contributions are what so-called [curators](@) of the [scope](@) seek to deliver. They are the ones that make sure that there is a [location](scopedir@) where people can contribute to the development of the [terminology](@) of a [scope](@), and tools are installed and operational that enable [authors](@) to use them as they publish their documents. [Curators](@) have their own [manual](/docs/manuals/curator). diff --git a/docs/tev2/terms/trrt.md b/docs/terms/trrt.md similarity index 96% rename from docs/tev2/terms/trrt.md rename to docs/terms/trrt.md index ab0e303fd8..cb64e1a900 100644 --- a/docs/tev2/terms/trrt.md +++ b/docs/terms/trrt.md @@ -13,7 +13,7 @@ status: proposed created: 2023-07-31 updated: 2023-07-31 contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/terms/versiontag.md b/docs/terms/versiontag.md similarity index 100% rename from docs/tev2/terms/versiontag.md rename to docs/terms/versiontag.md diff --git a/docs/tev2/terms/vocabulary.md b/docs/terms/vocabulary.md similarity index 100% rename from docs/tev2/terms/vocabulary.md rename to docs/terms/vocabulary.md diff --git a/docs/tev2/tev2-glossary.md b/docs/tev2-glossary.md similarity index 75% rename from docs/tev2/tev2-glossary.md rename to docs/tev2-glossary.md index 33e81b1824..1617c9f7a5 100644 --- a/docs/tev2/tev2-glossary.md +++ b/docs/tev2-glossary.md @@ -14,8 +14,8 @@ The entire section on Terminology Engine v 2 (TEv2) is still under construction. As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', i.e. not yet processed.
[readers](@) will need to see through some (currently unprocessed) notational conventions. ::: -[TEv2](@) 'eats its own dogfood' by documenting the [knowledge artifacts](@) that it uses, and using the tools in the [TEv2 toolbox](/docs/tev2/tev2-toolbox) as they become available. +[TEv2](@) 'eats its own dogfood' by documenting the [knowledge artifacts](@) that it uses, and using the tools in the [TEv2 toolbox](/docs/tev2-toolbox) as they become available. The current [knowledge artefacts](@) consist of -- a [mental model](@), called [Terminology Support](/docs/tev2/terms/patterns/pattern-terminology) (or [Self-Sovereign Terminology](/docs/tev2/terms/patterns/pattern-terminology)). +- a [mental model](@), called [Terminology Support](/docs/terms/patterns/pattern-terminology) (or [Self-Sovereign Terminology](/docs/terms/patterns/pattern-terminology)). - a set of [terms](@) that can be found by opening the `TEv2 Glossary` item in the sidebar \ No newline at end of file diff --git a/docs/tev2/tev2-overview.md b/docs/tev2-overview.md similarity index 55% rename from docs/tev2/tev2-overview.md rename to docs/tev2-overview.md index 9893621ed3..956c8c7af9 100644 --- a/docs/tev2/tev2-overview.md +++ b/docs/tev2-overview.md @@ -18,8 +18,8 @@ As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', The Terminology Engine (v2) is a set of specifications and tools that caters for the creation and maintenance (i.e. [curation](@)) of [terminologies](@), as well as for its subsequent use in publications of different types (e.g. websites, whitepapers) and formats (e.g. html, LaTeX), as appropriate for different, individual [scopes](@). The following perspectives are meant to help you get an overview of [TEv2](@) and its intended impact: -- **[Understanding One Another](/docs/tev2/overview/tev2-common-understanding)** is what it ultimately is all about. This perspective describes our take on this. -- **[Purpose](/docs/tev2/overview/tev2-purpose)**. This perspective states the objectives that we seek to realize with [TEv2](@). -- **[Design Principles](/docs/tev2/overview/tev2-design-principles)**. This perspective describes the main ideas behind the ways in which [TEv2](@) has been designed. -- **[Architecture](/docs/tev2/overview/tev2-architecture)**. This perspective provides an overview of the files, tools and how they interrelate. -- **[Terminology Support](/docs/tev2/terms/patterns/pattern-terminology)**. This perspective describes the mental model we use to think about what we're doing. +- **[Understanding One Another](/docs/overview/tev2-common-understanding)** is what it ultimately is all about. This perspective describes our take on this. +- **[Purpose](/docs/overview/tev2-purpose)**. This perspective states the objectives that we seek to realize with [TEv2](@). +- **[Design Principles](/docs/overview/tev2-design-principles)**. This perspective describes the main ideas behind the ways in which [TEv2](@) has been designed. +- **[Architecture](/docs/overview/tev2-architecture)**. This perspective provides an overview of the files, tools and how they interrelate. +- **[Terminology Support](/docs/terms/patterns/pattern-terminology)**. This perspective describes the mental model we use to think about what we're doing. diff --git a/docs/tev2/tev2-roles.md b/docs/tev2-roles.md similarity index 92% rename from docs/tev2/tev2-roles.md rename to docs/tev2-roles.md index 305e4fe4f5..fa3916ec6e 100644 --- a/docs/tev2/tev2-roles.md +++ b/docs/tev2-roles.md @@ -30,7 +30,7 @@ Contributors can also be tasked to check/proofread authored documents to ensure Finally, contributors may identify any specific needs or mechanisms that help them do the aforementioned tasks, and communicate these needs to their [curators](@), or otherwise contribute to the further development of [TEv2](@) so that such needs and mechanisms may be supported. -The [Manual for Contributors](/docs/tev2/manuals/contributor) documents how the [TEv2](@) supports this role. +The [Manual for Contributors](/docs/manuals/contributor) documents how the [TEv2](@) supports this role. ## Curators {#curator} @@ -40,7 +40,7 @@ A [curator](@) is tasked with describing the [scope](@) particulars, [curating]( Also, [curators](@) are expected to specify the processes that enable contributors and [authors](@) to contribute to the contents of the [scope](@) (e.g. by providing suggestions for texts, discussing them, etc.), specifically any conditions/requriements that they have to be aware of and take into account, and that are needed to enable the [curators](@) to do their job. -The [Manual for Curators](/docs/tev2/manuals/curator) documents how the [TEv2](@) supports this role. +The [Manual for Curators](/docs/manuals/curator) documents how the [TEv2](@) supports this role. ## Authors {#author} @@ -48,4 +48,4 @@ The [Manual for Curators](/docs/tev2/manuals/curator) documents how the [TEv2](@ [Authors](@) may also identify any specific needs or mechanisms that help them do the aforementioned tasks, and communicate these needs to their [curators](@), or otherwise contribute to the further development of [TEv2](@) so that such needs and mechanisms may be supported. -The [Manual for Authors](/docs/tev2/manuals/author) documents how the [TEv2](@) supports this role. +The [Manual for Authors](/docs/manuals/author) documents how the [TEv2](@) supports this role. diff --git a/docs/tev2/tev2-spec-files.md b/docs/tev2-spec-files.md similarity index 50% rename from docs/tev2/tev2-spec-files.md rename to docs/tev2-spec-files.md index dccca12005..afab0f1f4a 100644 --- a/docs/tev2/tev2-spec-files.md +++ b/docs/tev2-spec-files.md @@ -17,8 +17,8 @@ As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', [TEv2](@) expects [communities](@) to have directory that is easily accessible by IT tools, and in which - apart from other stuff it may keep there - is designated to contain all sorts of curated documentation. Thus, this directory (or one or more of its subdirectories) can be designated as [scope directories](@) for the [scopes](@) that the [community](@) owns. The [scopedir](@) may contain may contain lots of directories and files that are of no relevance for [TEv2](@), but it also contains files that are, such as: -- the **[Curated Texts](/docs/tev2/spec-files/ctext)**, which contain documentation on [knowledge artifacts](@) ([concepts](@), [mental models](@), etc.); -- the **[Scope Administration File (SAF)](/docs/tev2/spec-files/saf)**, which contains data about the [scope](@) itself, pointers to (the [scopedirs](@) of) other [scopes](@) that it relates to, and specifications of various versions of managed [glossaries](@); -- the **[Profile Templates](/docs/tev2/spec-files/profile-templates)**, i.e. templates that play a role in [text conversion steps](/docs/tev2/overview/tev2-design-principles#text-conversion-steps); -- the **[Machine Readable Glossary (MRG)](/docs/tev2/spec-files/mrg)**, which contains (machine readable) [MRG entries](@) that contain the various [terms](@) of a [scope](@) and pointers to the documentation of the [knowledge artifacts](@) that they refer to; -- the **[Human Readable Glossary (HRG)](/docs/tev2/spec-files/hrg)**, i.e. human readable equivalents of the [MRGs](@); +- the **[Curated Texts](/docs/spec-files/ctext)**, which contain documentation on [knowledge artifacts](@) ([concepts](@), [mental models](@), etc.); +- the **[Scope Administration File (SAF)](/docs/spec-files/saf)**, which contains data about the [scope](@) itself, pointers to (the [scopedirs](@) of) other [scopes](@) that it relates to, and specifications of various versions of managed [glossaries](@); +- the **[Profile Templates](/docs/spec-files/profile-templates)**, i.e. templates that play a role in [text conversion steps](/docs/overview/tev2-design-principles#text-conversion-steps); +- the **[Machine Readable Glossary (MRG)](/docs/spec-files/mrg)**, which contains (machine readable) [MRG entries](@) that contain the various [terms](@) of a [scope](@) and pointers to the documentation of the [knowledge artifacts](@) that they refer to; +- the **[Human Readable Glossary (HRG)](/docs/spec-files/hrg)**, i.e. human readable equivalents of the [MRGs](@); diff --git a/docs/tev2/tev2-syntax.md b/docs/tev2-syntax.md similarity index 50% rename from docs/tev2/tev2-syntax.md rename to docs/tev2-syntax.md index 25d99a0376..e861b35728 100644 --- a/docs/tev2/tev2-syntax.md +++ b/docs/tev2-syntax.md @@ -20,6 +20,6 @@ As TEv2 is not (yet) available, the texts that specify the tool are still 'raw', ::: [TEv2](@) uses specific syntaxes: -- the **[TermReference Syntax](/docs/tev2/spec-syntax/term-ref-syntax)** is the syntax allowed to author [TermRefs](@) (in source documents, see reference needed); -- the **[Form Phrases Syntax](/docs/tev2/spec-syntax/form-phrase-syntax)**, i.e. the syntax that [authors](@) need to specify [form phrases](@) (in the `formPhrases` field of [curated texts](@) - see the [curated text file specs](/docs/tev2/spec-files/ctext)); -- the **[Terminology Construction Syntax](/docs/tev2/spec-tools/terminology-construction)**, i.e. the syntax for the [term selection criteria](@) that [curators](@) need to specify the contents of a [terminology](@). +- the **[TermReference Syntax](/docs/spec-syntax/term-ref-syntax)** is the syntax allowed to author [TermRefs](@) (in source documents, see reference needed); +- the **[Form Phrases Syntax](/docs/spec-syntax/form-phrase-syntax)**, i.e. the syntax that [authors](@) need to specify [form phrases](@) (in the `formPhrases` field of [curated texts](@) - see the [curated text file specs](/docs/spec-files/ctext)); +- the **[Terminology Construction Syntax](/docs/spec-tools/terminology-construction)**, i.e. the syntax for the [term selection criteria](@) that [curators](@) need to specify the contents of a [terminology](@). diff --git a/docs/tev2/tev2-toolbox.md b/docs/tev2-toolbox.md similarity index 94% rename from docs/tev2/tev2-toolbox.md rename to docs/tev2-toolbox.md index 35792f4299..a725412514 100644 --- a/docs/tev2/tev2-toolbox.md +++ b/docs/tev2-toolbox.md @@ -9,11 +9,11 @@ import useBaseUrl from '@docusaurus/useBaseUrl' # TEv2 Terminology Toolbox -As mentioned in the [TEv2 overview](/docs/tev2/tev2-overview), the toolbox is envisaged to have a variety of tools, including: +As mentioned in the [TEv2 overview](/docs/tev2-overview), the toolbox is envisaged to have a variety of tools, including: - the **Term Ref(erence) Resolution Tool ([TRRT](trrt@))**. This tool takes files that contain so-called [TermRefs](@) and outputs a copy of these files in which these [TermRefs](@) are converted into so-called [renderable refs](@), i.e. texts that can be further processed by tools such as GitHub pages, Docusaurus, etc. The result of this is that the rendered document contains markups that help [readers](@) to quickly find more explanations of the [concept](@) or other [knowledge artifact](@) that is being referenced. -- the **MRG Importer ([MRG importer](@))**. This tool serves to get any [MRG](@) that may be needed within a particular [scope](@), and make it available in the [scope's](@) [glossarydir](@). The idea behind this is that various tools that may need such [MRGs](@) would not need to include such code. Further details are in the [MRG importer specs](/docs/tev2/spec-tools/mrg-importer). +- the **MRG Importer ([MRG importer](@))**. This tool serves to get any [MRG](@) that may be needed within a particular [scope](@), and make it available in the [scope's](@) [glossarydir](@). The idea behind this is that various tools that may need such [MRGs](@) would not need to include such code. Further details are in the [MRG importer specs](/docs/spec-tools/mrg-importer). - the **Machine Readable Glossary generation Tool ([MRGT](@))**. This tool reads the [SAF](@) of a [scope](@) to find the instructions by which it creates an [MRG](@) for each of the versions of the [terminology](@) that are maintained within that [scope](@). diff --git a/docs/tev2/23.2 b/docs/tev2/23.2 deleted file mode 100644 index e69de29bb2..0000000000 diff --git a/docs/tev2/terms/@.md b/docs/tev2/terms/@.md deleted file mode 100644 index 6a45ce8682..0000000000 --- a/docs/tev2/terms/@.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -# TEv2 Curated Text Header -term: "@" -termType: error -# Docusaurus \(see https://docusaurus\.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter\): -hoverText: Error - the reference cannot be resolved. -sidebar_label: Term ref not found -displayed_sidebar: tev2SideBar ---- - -# ERROR - The reference cannot be resolved - -# "@" - -You have clicked on a [term](@) that hasn't been (properly) defined. \ No newline at end of file diff --git a/docs/tev2/tev2-student-assignment.md b/docs/tev2/tev2-student-assignment.md deleted file mode 100644 index 2d0a6de5fa..0000000000 --- a/docs/tev2/tev2-student-assignment.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -id: tev2-student-assignment -sidebar_label: Student Assignment -hide_table_of_contents: true -scopetag: tev2 -date: 20220929 ---- - -import useBaseUrl from '@docusaurus/useBaseUrl' - -# Student Assignment - -This page explains what a group of students can do to create and contribute one or more tools to the toolbox of the Terminology Engine v2 ([TEv2](@)), that caters for -- the creation and maintenance (i.e. [curation](@)) of [terminologies](@), and -- the subsequent use in publications of different types (e.g. websites, whitepapers) and formats (e.g. html, LaTeX). - -## Context, Background - -The first part in understanding the assignment is to understand its context, what the needs are, how they are being adressed, and what the role of [TEv2](@) in all this is. - -Here are some pointers: -- The mission we try to realize (or at least contribute to), is **[Understanding One Another](/docs/tev2/overview/tev2-common-understanding)**. -- The **[Purpose](/docs/tev2/overview/tev2-purpose)** states the objectives that [TEv2](@) seeks to realize. -- The **[Design Principles](/docs/tev2/overview/tev2-design-principles)** are the main ideas behind the design of [TEv2](@). -- The **[Architecture](/docs/tev2/overview/tev2-architecture)** provides an overview of the data and the files that [TEv2](@) works with, as well as of the tools and how they interrelate. -- A more or less description of our way of thinking is provided as **[Terminology Support](/docs/tev2/terms/patterns/pattern-terminology)**. - -## Current status - -:::warning -Obviously, this section may be outdatet... -::: - -Currently (October 3, 2022), one tool is available, i.e. the [MRGT](/docs/tev2/spec-tools/21-mrgt.md), and it may be possible that one instance of the (currently not well-defined) [HRGT](/docs/tev2/spec-tools/22-hrgt.md) will be created. - -## Priorty tools - -Tools that we would like to see developed first include: - -- [TRRT](/docs/tev2/spec-tools/12-trrt.md), which converts [TermRef syntax](/docs/tev2/spec-syntax/11-term-ref-syntax.md) into one (out of multiple choices of) renderable syntax(es). -- ingress tools that convert wiki-files (and perhaps some other formats) into [curated texts](/docs/tev2/spec-files/00-ctext.md); -- rendering tools that are needed to accommodated terminology support for [ReSpec](https://dev.w3.org/2008/video/mediaann/ReSpec.js/documentation.html) environments, such as often used for W3C standards. \ No newline at end of file diff --git a/docs/tev2/unique.py b/docs/unique.py similarity index 98% rename from docs/tev2/unique.py rename to docs/unique.py index 91b79e10e9..fc54c0fb44 100644 --- a/docs/tev2/unique.py +++ b/docs/unique.py @@ -59,7 +59,7 @@ def process_excel_row(row): updated: {today} # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/unique_fields.xlsx b/docs/unique_fields.xlsx similarity index 100% rename from docs/tev2/unique_fields.xlsx rename to docs/unique_fields.xlsx diff --git a/docs/tev2/unique_py_specs.txt b/docs/unique_py_specs.txt similarity index 98% rename from docs/tev2/unique_py_specs.txt rename to docs/unique_py_specs.txt index b40f523d5d..b6baf51aed 100644 --- a/docs/tev2/unique_py_specs.txt +++ b/docs/unique_py_specs.txt @@ -37,7 +37,7 @@ created: {today} updated: {today} # Origins/Acknowledgements contributors: RieksJ -attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs/tev2)" +attribution: "[TNO Terminology Design](https://tno-terminology-design.github.io/tev2-specifications/docs)" originalLicense: "[CC BY-SA 4.0](http://creativecommons.org/licenses/by-sa/4.0/?ref=chooser-v1)" --- diff --git a/docs/tev2/zzz-broken-links-filter.rieks b/docs/zzz-broken-links-filter.rieks similarity index 100% rename from docs/tev2/zzz-broken-links-filter.rieks rename to docs/zzz-broken-links-filter.rieks diff --git a/docs/tev2/zzz-tev2-tmscript.rieks b/docs/zzz-tev2-tmscript.rieks similarity index 98% rename from docs/tev2/zzz-tev2-tmscript.rieks rename to docs/zzz-tev2-tmscript.rieks index 9e5df316c3..b15b9f9c99 100644 --- a/docs/tev2/zzz-tev2-tmscript.rieks +++ b/docs/zzz-tev2-tmscript.rieks @@ -39,7 +39,7 @@ reftext = "(ref1|ref2)(?=[^`]|%{eof})" // filter "docs/terms/identity.md" // filter "docs/**/*.md" -filter "docs/tev2/**/*.md" +filter "docs/**/*.md" // Convert quotes so that only two types remain: ' and " (which is helpful in specifying further regexes...) replace-regex "[‘’]" diff --git a/docusaurus.config.js b/docusaurus.config.js index a6ea9c1e0e..2197ec571f 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -25,8 +25,7 @@ module.exports = { title: 'Home', logo: { src: 'images/logos/tev2-new-babylon-medium.png', }, items: [ - { to: 'docs/tev2/tev2-overview', label: 'TEv2 Overview', position: 'left'}, - { to: 'docs/terminology-design/overview', label: 'Terminology Design', position: 'left'}, + { to: 'docs/tev2-overview', label: 'TEv2 Overview', position: 'left'}, { href: 'https://github.com/tno-terminology-design/tev2-specifications', label: 'Github', position: 'right', }, ], @@ -34,29 +33,21 @@ module.exports = { footer: { style: 'dark', links: [ - { - title: 'Terminology Design', - items: [ - { label: 'Introduction', to: 'docs/terminology-design/overview' }, - { label: 'Methods', to: 'docs/terminology-design/methods' }, - { label: 'Github', href: 'https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/terms' }, - ], - }, { title: 'TEv2 User Manuals', items: [ - { label: 'Curators', to: 'docs/tev2/manuals/curator' }, - { label: 'Contributors', to: 'docs/tev2/manuals/contributor' }, - { label: 'Authors', to: 'docs/tev2/manuals/author' }, + { label: 'Curators', to: 'docs/manuals/curator' }, + { label: 'Contributors', to: 'docs/manuals/contributor' }, + { label: 'Authors', to: 'docs/manuals/author' }, // { label: 'Github', href: 'https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/terms' }, ], }, { title: 'TEv2 Specifications', items: [ - { label: 'Files', to: 'docs/tev2/tev2-spec-files' }, - { label: 'Syntaxes', to: 'docs/tev2/tev2-syntax' }, - { label: 'Toolbox', to: 'docs/tev2/tev2-toolbox' }, + { label: 'Files', to: 'docs/tev2-spec-files' }, + { label: 'Syntaxes', to: 'docs/tev2-syntax' }, + { label: 'Toolbox', to: 'docs/tev2-toolbox' }, { label: 'Github', href: 'https://github.com/tno-terminology-design/tev2-specifications/tree/master/docs/terms' }, ], }, diff --git a/sidebars.js b/sidebars.js index 36a4351846..7b50a687bf 100644 --- a/sidebars.js +++ b/sidebars.js @@ -2,100 +2,63 @@ const sidebars = { tev2SideBar: [ { type: 'category', label: 'TEv2 Overview', - link: {type: 'doc', id: 'tev2/tev2-overview'}, + link: {type: 'doc', id: 'tev2-overview'}, items: [ - { type: 'autogenerated', dirName: 'tev2/overview' }, - { type: 'doc', label: 'Terminology Support', id: 'tev2/terms/patterns/pattern-terminology'}, + { type: 'autogenerated', dirName: 'overview' }, + { type: 'doc', label: 'Terminology Support', id: 'terms/patterns/pattern-terminology'}, ] }, { type: 'category', label: 'Roles', - link: {type: 'doc', id: 'tev2/tev2-roles'}, + link: {type: 'doc', id: 'tev2-roles'}, items: [ { type: 'category', label: 'Contributors', - link: {type: 'doc', id: 'tev2/manuals/contributor'}, + link: {type: 'doc', id: 'manuals/contributor'}, items: - [ 'tev2/manuals/contributors-wiki', - , 'tev2/manuals/contributors-repo', - , 'tev2/manuals/contributors-LaTeX', + [ 'manuals/contributors-wiki', + , 'manuals/contributors-repo', + , 'manuals/contributors-LaTeX', ], }, { type: 'category', label: 'Curators', - link: {type: 'doc', id: 'tev2/manuals/curator'}, + link: {type: 'doc', id: 'manuals/curator'}, items: - [ 'tev2/manuals/tev2-installation', - 'tev2/spec-tools/terminology-construction', + [ 'manuals/tev2-installation', + 'spec-tools/terminology-construction', ], }, - { type: 'doc', id: 'tev2/manuals/author'}, + { type: 'doc', id: 'manuals/author'}, ], }, { type: 'category', label: 'Files (Structure, Specs)', - link: {type: 'doc', id: 'tev2/tev2-spec-files'}, + link: {type: 'doc', id: 'tev2-spec-files'}, items: - [ { type: 'autogenerated', dirName: 'tev2/spec-files' } ] + [ { type: 'autogenerated', dirName: 'spec-files' } ] }, { type: 'category', label: 'Syntax (Specs)', - link: {type: 'doc', id: 'tev2/tev2-syntax'}, + link: {type: 'doc', id: 'tev2-syntax'}, items: - [ { type: 'autogenerated', dirName: 'tev2/spec-syntax' }, - { type: 'doc', id: 'tev2/spec-tools/terminology-construction', label: 'MRG Selection Criteria'}, + [ { type: 'autogenerated', dirName: 'spec-syntax' }, + { type: 'doc', id: 'spec-tools/terminology-construction', label: 'MRG Selection Criteria'}, ] }, { type: 'category', label: 'The Toolbox (specs)', - link: {type: 'doc', id: 'tev2/tev2-toolbox'}, - items: [ { type: 'autogenerated', dirName: 'tev2/spec-tools' } ] + link: {type: 'doc', id: 'tev2-toolbox'}, + items: [ { type: 'autogenerated', dirName: 'spec-tools' } ] }, { type: 'category', label: 'TEv2 Glossary', - link: {type: 'doc', id: 'tev2/tev2-glossary'}, - items: [ { type: 'autogenerated', dirName: 'tev2/terms' } ] + link: {type: 'doc', id: 'tev2-glossary'}, + items: [ { type: 'autogenerated', dirName: 'terms' } ] }, { type: 'category', label: 'Miscellanous', - items: [ { type: 'autogenerated', dirName: 'tev2/miscellaneous' } ] - }, - ], -terminologyDesignSideBar: [ - { type: 'category', - label: 'On Terminology Design', - link: {type: 'doc', id: 'terminology-design/overview'}, - items: [ - { type: 'autogenerated', dirName: 'terminology-design/overview' }, - { type: 'doc', label: 'Terminology Support', id: 'tev2/terms/patterns/pattern-terminology'}, - ] - }, - { type: 'category', - label: 'Activities', - // link: {type: 'doc', id: 'tev2/tev2-roles'}, - items: - [ { type: 'autogenerated', dirName: 'terminology-design/manuals' } ] - }, - { type: 'category', - label: 'Methods', - link: {type: 'doc', id: 'terminology-design/methods'}, - items: [ - { type: 'autogenerated', dirName: 'terminology-design/methods' }, - { type: 'doc', label: 'Terminology - Mental Model', id: 'tev2/terms/patterns/pattern-terminology'}, - ] - }, - { type: 'category', - label: 'Backgrounds', -// link: {type: 'doc', id: 'terminology-design/backgrounds'}, - items: [ - { type: 'autogenerated', dirName: 'terminology-design/backgrounds' }, - ] - }, - { type: 'category', - label: 'Glossary', - items: [ { type: 'autogenerated', dirName: 'terminology-design/terms' } ] - }, - { type: 'doc', label: 'Backlog / Work-in-Progress', id: 'terminology-design/backlog' + items: [ { type: 'autogenerated', dirName: 'miscellaneous' } ] }, ], }; diff --git a/src/pages/index.js b/src/pages/index.js index f6c682c594..1c1708da5e 100644 --- a/src/pages/index.js +++ b/src/pages/index.js @@ -47,18 +47,9 @@ function Home() { 'button button--outline button--secondary button--lg', styles.getStarted, )} - to={useBaseUrl('docs/tev2/tev2-overview')}> + to={useBaseUrl('docs/tev2-overview')}> Terminology Engine v2 -     - - Terminology Design - */}