general editing of the guide

Signed-off-by: henkvancann <[email protected]>

spec/16_foreword.md

@@ -15,7 +15,7 @@ The mission of the Trust over IP (ToIP) Foundation is to define a complete archi
 
 Any trade name used in this document is information given for the convenience of users and does not constitute an endorsement.
 
-This document was prepared by the ToIP Technical Stack Working Group.
+This document was prepared by the ToIP Concepts and Terminology Working Group.
 
 Any feedback or questions on this document should be directed to https://github.com/trustoverip/specification/issues
 

spec/20_introduction.md

@@ -9,51 +9,10 @@
 
 ## Introduction
 
-The Terminology Governance Guide is up-to-date guide of collected and assimilated expertise within Trust-over-IP with regard to Concepts and Terminology. It's objective is to offer a comprehesive description of various data stores, tools and processes to manage terminology in a consistent and reproducable manner. The process intents to keep track of who did what in which role.
-Authors of concepts & terminology use the Guide to produce internally and externally consistent specifications, they could look up how to reference term internally (refer to definitions within the own scope) and externally: refer to definitions externally, either within the own umbrella organisation (ToIP) other totally external (e.g. IETF).
-Curators of concepts & terminology have an insight were in the process consistency of terminology is validated by hand or by tools that verify the structure, defs, refs, abbreviation and aliasses that authors might use.
+The Terminology Governance Guide is an up-to-date guide of assimilated expertise within Trust-over-IP with regard to Concepts and Terminology. It's objective is to offer a comprehesive description of various data stores, tools and processes to manage terminology in a consistent and reproducable manner. The process intents to keep track of who did what in which role.
 
-There is a brief history to the Guide. In 2021 TrustoverIP published the [Specification for Creating and Using Terms](https://wiki.trustoverip.org/display/HOME/Specification+for+Creating+and+Using+Terms)
+*Authors* of concepts & terminology use the Guide to produce internally and externally consistent specifications, they could look up how to reference term internally (refer to definitions within the own scope) and externally: refer to definitions externally, either within the own umbrella organisation (ToIP) other totally external (e.g. IETF).
 
-In the years to follow the guide to create [Term wikis](https://wiki.trustoverip.org/display/HOME/Terms+Wikis) has been established. It gives extensive instructions on how to create wikis, use markdown and hyperlinks, etc.
+*Curators* of concepts & terminology have an insight were in the process consistency of terminology is validated by hand or by tools that verify the structure, defs, refs, abbreviation and aliasses that authors might use.
 
-As the number of implementations grew, maintenance of the wikis became out of sync, the number of broken links increased, duplicate definitions of terms and deviations from the structure and governance offered.
-
-> Darrell O'donnell: As I am deep in a rabbit hole looking at definitions a thought occured to me. We may end up with “over-defined” terms - meaning the definition exists in multiple places. Have you considered that case?
-> I believe that a ToIP Master : ToIP Specification conflict should be avoided. If a spec needs a different term than is in the Master glossary, then the conflict should be resolved:
-adjust Master Glossary; or
-create new term in Spec
-> BUT where we end up looking at terms that are managed even further afield, this gets really hard.
-Just curious if this is a condition you’ve thought of.
-> I see the following possibilities:
-> - multiple def: in single document (this is just sloppy work - but easy to do, for me at least)
-> - duplicated def: - say in Spec and ToIP Master Glossary
-
-::: note Basic Note
-  [Check quickly out](https://henkvancann.github.io/terminology-governance-guide/#system-feature-consistency) how we take on these concerns
-:::
-
-Some of these developments are part of the natural evolution of concepts and terminologies within an umbrella organisation like ToIP. Others could be more streamlined.
-
-This specification intends to offer a *[[ref: Guide]]*. A Guide has little or no normative statements as it describes an advise on how to create a specific terminology by sticking to guidance and certain rules to know how to **write or adopt definitions**, how to reference them and where to store and manage them:
-
-- reuse the **specification template** and how to do this in a sustainable manner
-- reuse the **ToIP over-arching glossary** where possible
-- avoid breaking links in the future
-- use the full power of **def, refs and aliases** in individual documents based on Spec-Up (which is behind specification template as of 202?)
-- be able to generate your documents in a few leading **style-guides** like ToIP, ISO, etc.
-- Last but not least: any group with a certain scope will need to **source manage their own definitions** or views on definition, which means that we need to ear mark creation and updates with time & author.
-
-## Historical perspective
-
-### Past Practise Terminology Governance
-
-![Past Practise Terminology Governance](https://github.com/henkvancann/terminology-governance-guide/blob/be980e063e99f97cbb14093735ed42d9e8d617e2/images/past-practice-terminology-gov.png?raw=true)
-
-### Current Practise Terminology Governance
-
-![Current Practise Terminology Governance](https://github.com/henkvancann/terminology-governance-guide/blob/be980e063e99f97cbb14093735ed42d9e8d617e2/images/current-practice-terminology-gov.png?raw=true)
-
-### Future Practise Terminology Governance
-
-![Future Practise Terminology Governance?](https://github.com/henkvancann/terminology-governance-guide/blob/be980e063e99f97cbb14093735ed42d9e8d617e2/images/future-practice-terminology-gov.png?raw=true)
+There is a brief history to the Guide in the [annex](#Annex). 

spec/24_scope.md

@@ -7,25 +7,21 @@
 
 ## Scope
 
-This Guide goes with the flow as much as it can. This means:
+This Guide uses tools currently in use and proven open-source technology as much as possible:
+
 - git and github for version control, issue-handling and project management in the own github repo
+- GitHub user management
 - The existing Slack group CTWG for discussions
 - Use of github wiki-based source management of terminologies
-- Proposal to archive obsolete sources of terminology
+- Archive obsolete sources of terminology
 - Reuse harvesting / consensus creation tools that are available and anticipate improvements of those
 - Connect to TEv2 step by step
 - Use Spec-Up / specification template and anticipate improvements of this
 
 ### Roadmap
 
-Let's clear up the issues around TEv2 versus Spec-Up and KERISSE tooling. The goal is unification and we prevent reinventing tools that are already in place.
-
-The issue of unification is open, and it might be solved. By whom is not yet clear. A sequence numbered roadmap to unification (presumming that that's the goal) can be found below.
-
-
-##### Temporary solution: pictures
-
-![past](https://github.com/henkvancann/terminology-governance-guide/blob/fab622598a0bc03d0fedb62ea989572e082ae6bb/images/Gantt%20Diagram%20temporary%20past.png?raw=true)
+How do TEv2, Spec-Up and KERISSE relate? The goal is unification and we prevent reinventing tools that are already in place. 
 
-![future](https://github.com/henkvancann/terminology-governance-guide/blob/fab622598a0bc03d0fedb62ea989572e082ae6bb/images/Gantt%20Diagram%20temporary%20future.png?raw=true)
+The issue of unification is currently open, but it might be solved with the design of this Guide. A sequence numbered roadmap to unification (presumming that that's the goal) can be found below.
 
+| TBW | 

spec/32_howto_define.md

@@ -35,8 +35,10 @@ But unfortunately **not together with referencing existing poorly-formulated def
 
 ### Towards automatic processing in github actions
 
+Currently we allow for four types of source management tools of terminologies in ToIP context. 
+Check them out here: | TBW Link to the chapter |.
 
-Currently github wikis serve as the source management tool of the glossary terms in ToIP context. There are temporary exceptions.
+This example uses the github.com wiki of the target repository, but the other source management options could adopt the same guidelines for designing and editing a terminology in ToIP context. 
 
 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. Because we'd like to know about new definitions, flant them in discussions or social media: throw links!
@@ -50,7 +52,9 @@ Here are a few [practical rules](https://wiki.trustoverip.org/display/HOME/Terms
 _Have fun CRU-ing!_  
 '* CRU=Create Read Update
 
-### A glossary "reads" this wiki
+### A glossary "reads" this 
+
+| TBW this section is draft and incomplete|
 
 Where as the wiki source management tool (or *input tool*) of terminology, there is no way to add metadata to the terminology.