added desctiptions of roles

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

docs/how-can-determine-spec-up-t.md

@@ -0,0 +1,14 @@
+
+---
+sidebar_position: 1
+---
+
+# How can I determine Spec-Up-T
+
+Whether a site is generated by Spec-Up-T can be determined by the following:
+
+1. Inspect the code
+A. Open the index.html file with a text editor, or
+B. Chose inspect source (Option-Command-i on MacOS, Ctrl-Option-i on Windows)
+
+2. Find { @Kor: whaet specifically could be looking for?}

docs/various-roles/content-authors-guide/introduction.md

@@ -4,10 +4,26 @@ sidebar_position: 1
 
 # Intro
 
-:::warning
-Under construction
-:::
+## Use cases
 
-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.
 
+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 specificatio.
+
+### A. Write content 
+Content in markdown will be processed by Spec-Up-T. There is extra functionality in Spec-Up-T to reference
+1. Write your standardization/specification in `.md` in the `spec` directory, either locally on your computer or on gtihub.com. 
+2. `[[ref: ]]` terms that you have definitions of, available in the Spec-Up-T-based terminology section
+3. `[[xref: ]]` terms that you have definitions of, available in the Spec-Up-T-based terminology section of hosted glossaries by others.
+4. In case you use 3., then specify the repo in your `specs.json` file, before you can start referencing them.
+5. In case you use 2., 3. and 4. a content author can check the versions and its management of the own terminology section and also of the hosted glossaries. And pick the right form of a reference: either 2 or 3 of the plain URLs to a specific version of a term. 
+
+### B. Save the modifications
+With sufficient user-rights on a repo a content author can directly write changes to a repository. This is done via the `git push` command. Sometimes a content author does not have to explicitly use this command. For example if you use the github.com editor with sufficient user-rights as a logged-in user, than the push (and execution of invoked scripts by this push) will automatically follow.
+
+### C. Offer changes as a PR
+Without sufficient user-rights you can still offer the changes to the repo. Follow use case B, and then automatically your edit will go into the PR route on github.com.
+
+On a local machine you won't be able to push the changes to the production server. Instead you might want to push the changes to your own user-account on github.com and from there offer a PR on the destination repo.
+
+### D. Check technical consistency
 He/she uses browser extensions to check technical consistency of the links in the text and harvests a personal collection of term definitions.

docs/various-roles/curators-guide/introduction.md

@@ -4,17 +4,20 @@ sidebar_position: 1
 
 # Intro
 
-:::warning
-Under construction
-:::
+## Use cases
 
-Uses an IDE and git and browser extensions to check the overall content of a specification and logical consistency & meaning of term definition in a particular context.
+1. Uses an IDE and git and browser extensions to check the overall content of a specification and logical consistency & meaning of term definition in a particular context.
 
-The curator uses browser extensions to harvest a personal collection of term definitions based on those recommended by the specification authors.
+2. The reader uses browser extensions to harvest a personal collection of term definitions based on those recommended by the specification authors.
+
+**A curator can:**
 
-A curator can:
 Fork a Spec-Up-T repo to his/her user account on GitHub.com
+
 Optionally fetch and merge this repo to an IDE on a local computer.
+
 Configure the user account to publish the GitHub pages generated by Spec-Up-T
+
 Push change to the user account of the curator to show the admin role
+
 Offer a PR with changes and compare them across forks.

docs/various-roles/readers-guide/introduction.md

@@ -4,8 +4,20 @@ sidebar_position: 1
 
 # Intro
 
-:::warning
-Under construction
-:::
+## Use case
 
-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.
+Please consider that any Spec-Up-T-based website is generated through the execution of a few commands. This can be done either on the local machine or we use github.com to execute those necessary commands in github action scripts.
+
+### A. Read
+Uses github pages (github.io) website, or the plain index.html file generated by Spec-Up-T anywhere it is hosted. He/she reads concepts in text and terminology in the glossary-section of the document. 
+
+If this glossary section is generated by Spec-Up-T [(How can I tell that it's a Spec-Up-T-based glossary?)](../../how-can-determine-spec-up-t), then its tailor-made contextual glossary will generate pop-ups here and there in the text offered. Those can be read as well as the definition section too. Both will generate the same text. However, the definition section in the document will have more functionality then the pop-ups.
+
+### B. Send link
+Use cases A plus the definition section offers an anchor to a term definition. Click the anchor symbol before the term and it'll automatically be copied into the clipboard of the device you're using.
+Now the link can be pasted anywhere you like.
+
+### C. Check metadata
+
+Use cases A plus the definition section offers buttons to the version management system behind the terminology/glossary. This metadata tells a reader who accepted a change to the terminology, when and exactly what it consisted of. Who is a github user account; therefore we trust git and github.com for consistency, identification and authorization. Not always is the person who accepts the changes (admin) als the person that created the change (terminology-author!). A reader can get an inside in the whole acceptance process of a certain change, as long as it is in the same repo.
+This last requirement indicates that the sources of `xrefs` do not have a full version management history available in the referencing repository. Readers of metadata have to be aware of this exception.