Merge remote-tracking branch 'origin/main'

docs/general/windows-and-linux-installation.md

@@ -0,0 +1,101 @@
+# Difference between MacOS installation instructions and Windows or Linux instructions
+
+## Windows
+
+Here are the differences between the original **macOS instructions** and the modified **Windows-specific instructions**:
+
+1. **Terminal Type and Command Differences**:
+   - **macOS**: Uses `Terminal` and general `bash` commands.
+   - **Windows**: Uses **Command Prompt** or **PowerShell** instead of `Terminal`.
+   - The command lines for `npx` and directory navigation are modified to explicitly reference PowerShell.
+
+   ### Example
+   - **macOS**: 
+     ```bash
+     npx create-spec-up-t my-spec-up-t-website
+     ```
+   - **Windows**:
+     ```powershell
+     npx create-spec-up-t my-spec-up-t-website
+     ```
+
+2. **Directory Navigation**:
+   - **macOS**: General command `cd my-spec-up-t-website` is the same, but assumed to run in macOS Terminal.
+   - **Windows**: Specified as using PowerShell or Command Prompt, with `cd` unchanged.
+
+   ### Example
+   - **macOS and Windows**:
+     ```bash
+     cd my-spec-up-t-website
+     ```
+
+3. **Command Syntax for Install Dependencies**:
+   - **macOS**: General usage of `npm` command with no specific shell mentioned.
+   - **Windows**: Specifies running `npm` commands in PowerShell.
+
+   ### Example
+   - **macOS**:
+     ```bash
+     npm run install
+     ```
+   - **Windows**:
+     ```powershell
+     npm run install
+     ```
+
+4. **Environment Testing**:
+   - **macOS**: Terminal and general `bash` or zsh commands are assumed.
+   - **Windows**: Adds instructions to verify installation with PowerShell using `node -v`, `npm -v`, and `git --version` commands in PowerShell.
+
+## Linux
+
+Here are the differences between the original **macOS instructions** and the modified **Linux-specific instructions**:
+
+1. **Terminal Type and Command Differences**:
+   - **macOS**: Uses `Terminal` with general `bash` commands.
+   - **Linux**: Uses `Terminal` with `bash` commands, similar to macOS, but provides additional installation steps specific to Linux systems (e.g., using `apt-get` for installing Node.js and Git).
+
+   ### Example
+   - **macOS**:
+     ```bash
+     npx create-spec-up-t my-spec-up-t-website
+     ```
+   - **Linux**:
+     ```bash
+     npx create-spec-up-t my-spec-up-t-website
+     ```
+
+2. **Node.js and Git Installation**:
+   - **macOS**: Assumes Node.js and Git are downloaded and installed via their respective installers.
+   - **Linux**: Adds specific commands for installing Node.js and Git through the package manager (`apt-get` for Debian-based systems).
+
+   ### Example
+   - **Linux**:
+     ```bash
+     curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+     sudo apt-get install -y nodejs
+     sudo apt-get install git
+     ```
+
+3. **Environment Testing**:
+   - **macOS**: Assumes installation verification with general `bash` commands.
+   - **Linux**: Adds instructions for verifying installation in `bash` using `node -v`, `npm -v`, and `git --version`.
+
+   ### Example
+   - **macOS and Linux**:
+     ```bash
+     node -v
+     npm -v
+     git --version
+     ```
+
+4. **Package Installation and Directory Navigation**:
+   - **macOS**: Uses `Terminal` commands without additional setup.
+   - **Linux**: Uses `Terminal` commands similarly, with no changes for directory navigation or `npm` commands, as Linux and macOS share similar shell environments.
+
+   ### Example
+   - **macOS and Linux**:
+     ```bash
+     cd my-spec-up-t-website
+     npm run install
+     ```

docs/intro.md

@@ -33,6 +33,39 @@ Supporting roles are:
 - [admins](./various-roles/admins-guide/introduction.md)
 - [developers](./various-roles/developers-guide/intro.md)
 
+### Real-life example KERI team
+
+We have KERI specifications that consist of content and terminology. Let's take the KERI spec as an example. A `reader` could be anyone interested in the spec:
+- studying KERI
+- contributing to KERI in team
+Contributing to any Spec-Up-T-based specification can be of type:
+- `curator`
+- `content author` or editor
+- `terminology author` or editor
+
+Any specifcation has a **content** part and a Terms and **Definitions** section. In real life they appear in the same document. There'll be one chapter called Terms and Definitions, into which Spec-Up-T generates all the term defnitions. All the other chapters (if present) are considered 'content'. For example the chapter "[KERI Foundational Overview](https://trustoverip.github.io/tswg-keri-specification/#keri-foundational-overview)".  
+However, through all the chapters, including the Terms and Definitions chapter itself, references to the Terms & Definition may occur and literally pop-up for the `reader`.
+
+> KERI inventor *Samuel Smith* can be a `reader` of the spec, but will most probably quickly turn into a `curator`, `content author`, and `terminology author`.
+
+> *Henk van Cann* has written 90% of all KERI definitions, he's a typical `terminology author`. *Kent Bull* has been a curator for quite a few **definitions** of Henk because of Kent's native tongue and extensive KERI knowledge.
+
+> *Phil Pfeairheller* is a typical user of term defnitions. Generally he is a `content author` of specifications in the KERI team, whenever he sees a term that is not yet defined, he might create a definition on-the-fly if needed.
+
+Note that any specification could use only **definitions** of other glossaries. And xref to those glossaries. This is rather uncommon because if your specifying, you most probably construct new concepts whithin a new mental model.
+
+*Drummond Reed* is `terminology author` of the ToIP main glossary. The main glosary has *hardly any content section*. All other terminology authors and content authors can use the Main ToIP glossary by `xref`-ing to it, as a plain Spec-Up-T link "[[xref: glossary, term ]]" even in their own `def`s to explain the difference between the mental model of the term in the smaller context vs. the broader ToIP context.
+
+So most probably per repo the term **definitions** will be a mixture of:
+- full-URL links to external glossaries and resources
+- `xref`s to other Spec-Up-T based glossaries
+- `ref`s to `def`s present in the own Terms and Definition section
+- the `def` section will contain `ref`s and `xref`s too to other terms
+
+The more `xref`s a specification and team is able to use the more consensus is build in the broader community. For example: Henk van Cann will sync all terms that the KERI team uses with the one that IoIP uses in the main ToIP glossary.
+
+### Formal roles and flow
+
 ```mermaid
 flowchart
 %% Henk van Cann, Sept 27th 2024