diff --git a/spec/design.md b/spec/design.md index 9d5b5b5..8a099a1 100644 --- a/spec/design.md +++ b/spec/design.md @@ -6,9 +6,19 @@ "Please let me just write my document and add some glossary items and we’re done. We skip all the academic hassle about *meaning, concepts, artefacts* and what have we. Let’s get work done!” -### Do not proceed if +### Do not proceed if... -You recognize a few of those remarks above? If communication and understanding each other were just that easy, we could leave the hard part out. But **we can't skip the design of terminology** if we want to convey a (new) concept. +Cliff hanger! First, do you recognize a few of the emotional remarks above (under "Terminology design aids")? + +Why can't we give in? Simply skip the nerdy stuff? The reason is devastatingly basic: + + If communication and understanding each other were just that easy, we could leave the hard part out. + +But **we can't skip the design of terminology** if we want to convey a (new) concept and make sense for other people. + +::: warning Alert +Since we've just told you, you can only *knowingly* neglect the duty of designing proper terminology. +::: **Do not proceed with this chapter if you're a sender, only sending or broadcasting.** @@ -257,7 +267,7 @@ A[A:I am writing, but I need to explain something! Help!];B{B:Terms understood?} ### Wrap up -Isn’t the magic word "Criteria" a bit cruel? It might snatch average human beings in the heart of their weakness: understanding others. Yet "mutual understanding" is needed to be able to formulate criteria. +Isn’t the magic word "Criteria" a bit cruel? It might snatch average human beings in the heart of their weakness: understanding others. Yet "mutual understanding" is needed to be able to formulate suitable criteria. ### Move forward diff --git a/spec/howto_define.md b/spec/howto_define.md index 742ba07..0ecf030 100644 --- a/spec/howto_define.md +++ b/spec/howto_define.md @@ -39,7 +39,7 @@ But unfortunately **not together with referencing existing poorly-formulated def Currently github wikis serve as the source management tool of the glossary terms in ToIP context. There are temporary exceptions. Here are a few [practical rules](https://wiki.trustoverip.org/display/HOME/Terms+Wikis) from the originator ToIP to get these wiki terms through their equivalent [github actions script](https://github.com/WebOfTrust/WOT-terms/actions/workflows/content-fetch-and-deploy-update-glossary.yml), please: -1. beware all new wiki items you **create**, lead to new .md files. We'd like to know +1. beware all new wiki items you **create**, lead to new .md files. Because we'd like to know about new definitions, flant them in discussions or social media: throw links! 2. introduce lowercase names with spaces (they will convert into lower case names with dashes between the words) 3. start with **## Definition** header; [example](https://github.com/WebOfTrust/WOT-terms/wiki/composable-event-streaming-representation) 4. start with uppercase abbreviations with only the "**## See**" header; [example](https://github.com/WebOfTrust/WOT-terms/wiki/CESR) diff --git a/spec/roles.md b/spec/roles.md index 1f7bb63..15c5934 100644 --- a/spec/roles.md +++ b/spec/roles.md @@ -9,7 +9,7 @@ A clear specification of roles in- and outside an average ToIP "group" might cle 2. then the necessary consecutive steps to get there ### Role: ToIP glossary maintainer -Uses: Source management tool. Reads and compares concepts in text and terminology in glossaries, (for example generated by Spec-Up) to use within his/hers "own" over-arching ToIP glossary. He/she builds as muchn consensus around terms and concepts and promotes using the ToIP glossary as reference material. +Uses: Source management tool. Reads and compares concepts in text and terminology in glossaries, (for example generated by Spec-Up) to use within his/hers "own" over-arching ToIP glossary. He/she builds as much consensus around terms and concepts and promotes using the ToIP glossary as reference material. ### Role: Specification author Uses: an IDE, git and a browser extension, to edit Spec-Up markdown files for his/her specific context (mental model) in a version managed environment, authenticated, to write the concept and specification and offer this as a PR. He/she uses browser extensions to check technical consistency of the links in the text and harvest a personal collection of term definitions. @@ -20,10 +20,6 @@ Uses an IDE and git and browser extensions, to check logical consistency & meani ### Role: Reader Uses github.io website, reads concepts in text and terminology in glossaries, (for example generated by Spec-Up) with its own tailor-made contextual glossary that generates pop-ups here and there in the text offered. -### Process and roles - -![Glossary workflow](https://github.com/henkvancann/terminology-governance-guide/blob/0524440f9207588406b6865fa472165fdf6fac15/images/Darrell-Glossary-Workflow.jpeg) -*By: Darrel O'Donnell, Jan 2024* ### Questions and usecases