Merge pull request #9 from henkvancann/main

Use case description and roles
trustoverip · Sep 27, 2024 · 1aaf1a0 · 1aaf1a0
2 parents da8be5d + 7ef2eb2
commit 1aaf1a0
Show file tree

Hide file tree

Showing 6 changed files with 125 additions and 32 deletions.
diff --git a/docs/intro.md b/docs/intro.md
@@ -6,7 +6,38 @@ sidebar_position: 1
 
 ## Intro
 
-**Spec-Up-T** is a tool that helps you write specifications. It is a tool for writing in Markdown and creates *one* `index.html` file.
+**Spec-Up-T** is a tool that helps you write specifications. Specifications in Spec-Up-T have two main parts:
+* content 
+* term definitions
+
+Content is stored in markdown files under the `spec` directory, Terms definition optionally in various languages and optionally in various user levels are stored in the `terms-definitions` folder also in the spec directory.
+
+The two parts content and term definitions also illustrate the two main use cases of Spec-Up-T both resulting in single-file html servable from any webserver:
+- a glossary (fat terms section, slim content section)
+- a standardization specification (slim terms section, fat content section)
+
+> An example **glossary** is the [Main TrustoverIP glossary](https://github.com/trustoverip/ctwg-main-glossary)
+> An example **standard specification** is the [DID:Webs specification](https://github.com/trustoverip/tswg-did-method-webs-specification)
+
+## # Use cases and roles in Spec-Up-T
+
+Spec-Up-T is a technical specification and standardization tool, which a special focus on termninology: definiton and (externally) referencing terms and the version management of this complex.
+
+We have distinguished the following **roles**:
+- [terminology-authors](./various-roles/terminology-authors-guide/introduction.md)
+- [content-authors](./various-roles/content-authors-guide/introduction.md)
+- [curators](./various-roles/curators-guide/introducion.md)
+- [readers](./various-roles/readers-guide/introduction.md)
+
+Supporting roles are:
+- [admins](./various-roles/admins-guide/introduction.md)
+- [developers](./various-roles/developers-guide.md)
+
+All the **use cases** are specified under the roles above. Click the links to get there.
+
+## Technical presence
+
+It is a tool for writing in Markdown and creates *one* `index.html` file.
 
 - You write your texts in [Markdown](https://www.markdownguide.org/getting-started/)
 - You use an editor (IDE) or you use GitHub's web editor

diff --git a/docs/various-roles/admins-guide/introduction.md b/docs/various-roles/admins-guide/introduction.md
@@ -4,4 +4,54 @@ sidebar_position: 1
 
 # Intro
 
-No content yet.
+An Admin role is a supporting role in Spec-Up-T. 
+
+## Use cases
+
+1. The Admin splits a terminology file that contains multiple definition in spec-up syntax (mostly originated from a terminology editor) into single definition files in the right subdirectory of the terms-definition directory.
+
+2. The Admin updates the **npm package called Spec-Up-T**. This is relevant when modules are depreciated or new modules offer crucial features.
+
+3. The Admin update its **own installation**, which he installed with the installer, using the Spec-Up-T npm package.
+
+4. _Not yet operational!_ The Admin adds a new language subdirectory to terms-definition directory and specifies the right API calls to chatGPT for a language and/or user-level translation from the source terms definition.
+
+## Solutions
+
+### Add 1. Convenience tool splitting a file into atomic single definition files
+The input of a [Splitter tool](./tools.md#splitter-tool) is a markdown file with multiple spec-up definition, references, and external references. 
+
+You can do the splitting operation by hand, the splitter tool is just a convenience tool for large glossaries.
+
+### Add 2 and 3. Updates
+Use case 2, [update Spec-Up-T](./updating.md#updating-the-npm-package-called-spec-up-t), has to be followed by Use cases 3: [Update own installation](./updating.md#updating-your-installation)
+
+### Add 4. Languages
+_Not yet operational!_ However, The design is:
+
+#### Data
+_Not yet operational!_ 
+- one reference source language, which is English for example
+- the most comprehensive definition of concept covered by a term
+- it matches the Spec-Up-T directory structure: atomic definitions in markdown files with spec-up syntax under a `terms-definition` folder in the `spec` folder.
+- per language-userlevel an extra subdirectory with this naming convention:
+   _languagecode-LVL1_, _languagecode-LVL2_, ..., _languagecode-LVLn_
+
+   Since the reference source-files are LVLn, where n is the most comprehensive description.
+
+
+#### Functionality
+_Not yet operational!_ 
+ - AI will convert the reference source data and export the resulting files into directories named in this convention:
+
+  _languagecode-LVLx_
+
+For example:
+EN is the reference language and we have one other language (Dutch) and two user levels in total.
+
+`terms-definition` folder contains:
+
+- files that have the characteristics: English, user level 2.
+- subdirectories EN-LVL1, NL-LVL1, NL-LVL2
+
+An essential feature of this AI conversion is the linking back to the original source in the generated content. So a Reader always has a reference back to the curated source in the original language. Just imagine how important this is in legally enforced specifications: you don't want to be liable for over-simplified or incorrectly translated rules and regulations.
diff --git a/docs/various-roles/glossary-maintainers-guide/_category_.json b/docs/various-roles/glossary-maintainers-guide/_category_.json
diff --git a/docs/various-roles/glossary-maintainers-guide/introduction.md b/docs/various-roles/glossary-maintainers-guide/introduction.md
diff --git a/docs/various-roles/intro.md b/docs/various-roles/intro.md
@@ -12,5 +12,7 @@ Spec-Up-T implementations can distinguish the following roles:
 | Terminology Author | Focusses on term definitions covering concepts of the group he/she belongs to.| [Terminology Author Guide](terminology-authors-guide/introduction.md) | [Understand Markdown](technical-skills-needed#4) |
 | Curator            | Checks overall content and logical consistency & meaning of term definition in a certain context.  | [Curator Guide](curators-guide/introduction.md) | [Understand Markdown](technical-skills-needed#4) |
 | Reader             | Reads concepts in text and terminology in glossaries.                         | [Reader Guide](readers-guide/introduction.md)            | [Understand the web](technical-skills-needed#5) |
-| Admin              | Installs, updates, and maintains Spec-Up-T.                                    | [Admin Guide](admins-guide/introduction.md)                           | [Understand Node and NPM](technical-skills-needed#1), [Understand file system](technical-skills-needed#2), [Understand debugging](technical-skills-needed#7) |
-| Developer          | Adds new functionality to Spec-Up-T.                                          | [Developer Guide](developers-guide.md)                   | [Understand Git and Github](technical-skills-needed#6) |
+| _Admin_              | Installs, updates, and maintains Spec-Up-T.                                    | [Admin Guide](admins-guide/introduction.md)                           | [Understand Node and NPM](technical-skills-needed#1), [Understand file system](technical-skills-needed#2), [Understand debugging](technical-skills-needed#7) |
+| _Developer_          | Adds new functionality to Spec-Up-T.                                          | [Developer Guide](developers-guide.md)                   | [Understand Git and Github](technical-skills-needed#6) |
+
+_Supporting roles in italic_
diff --git a/docs/various-roles/terminology-authors-guide/introduction.md b/docs/various-roles/terminology-authors-guide/introduction.md
@@ -4,12 +4,45 @@ sidebar_position: 1
 
 # Intro
 
-:::warning
-Under construction
-:::
+A terminology author focusses on term definitions covering concepts of the group he/she belongs to. By far the most terminology author will use links to other glossaries, that may or may not be based on Spec-Up-T. They simply copy links and make references in their own text. Which is perfectly fine.
 
-Focusses on term definitions covering concepts of the group he/she belongs to.
+Uses: a text editor. That is the minimal setup. When done he/she publishes the result on the web somewhere as a webpage, for example in `html`.
 
-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.
+## Use cases
+
+Besides a simple text editor, a terminology author could use 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 harvests a personal collection of term definitions. Specification author terms that cover those concepts.
+
+These are example uses that we will step-by-step elaborate on.
+
+### A. Use definition
+
+1. Go to the Spec-Up-T glossary, where the definition is listed
+2. Copy the persistent URL
+3. Paste the persistent URL, save and publish
+  - at face value
+  - in a link
+
+Why is a Spec-Up-T based glossary interesting to link to? -> version management!
+
+### B. Amend a definition
+
+Follow A.
+
+1. Add text to the definition, save and publish 
+
+How will you maintain this definition? How will you cooperate with others on the definition or a whole list of definitions. Just try to imagine how this play out.
+
+This is why Spec-Up-T came to be.
+
+
+### C. Create your own terminology using Spec-Up-T
+
+Why Spec-Up-T? -> version management
+
+Follow A. en B. above.
+
+1. Get a git-based version management environment, create a repo there
+2. Install Spec-Up-T
+3. etc.