[PROCESS] ToIP Deliverables Process compliant glossary proposal

[vinomaster]

CTWG Process Proposal

This issue offers a proposal for a tactical solution to the glossary generation process supported by the CTWG on behalf of the entire ToIP Foundation community.

Status Assessment

The CTWG has been struggling for nearly nine months to strike a balance between:

• Available developer skills
• Curator resources
• Prioritization of ToIP and external organization requirements

In the spirit of Issue 22 - Glossary Generation and Issue 23 - Consumability we SHOULD be focused on the following basic objectives in the CTWG:

1. Definition of a data model for Terms and Concepts
2. Curation process for Terms and Concepts
3. Tool agnostic use of a CTWG maintained corpus of terms and concepts

Recently, members of the CTWG created the trustoverip/ctwg-sandbox repo for the experimentation of glossary production. This endeavor was helpful for members to visualize an example of an end-to-end glossary generation process using file-system-based markdown content as opposed to a centralized datastore.

At the same time, the ToIP Foundation has been trying to execute on the delivery of an initial set of deliverables by end of 1Q21. This plan pressure influenced a call for a vote along with complimentary discussion associated with the trustoverip/ctwg-sandbox repo solution for the delivery of these 1Q21 ToIP deliverables.

While the broader CTWG members appreciate the time and efforts of the subset of CTWG members that participated in the trustoverip/ctwg-sandbox research, the solution outcome COULD be summarized as:

Objective	Pass/Fail Assessment	Comment
1. Definition of a data model for Terms and Concepts	Pass	However, the metadata in the data model assumes consumption by a specific tool. Current status lacks an extraction mechanism that hides the internal metadata during glossary generation process.
2. Curation process for Terms and Concepts	Unclear	It seems that lessons have been learned on how to curate terms and concepts in a file-system-based corpus of markdown content but the declaration (description) of the internal CTWG process seems to be lacking.
3. Tool agnostic use of a CTWG corpus of terms and concepts	Fail	This experiment ignored an investigation into Issue 17 - Tool Assessment and it produced a tool dependent solution that is incompatible with the existing ToIP Deliverables Process Requirements.

It is also important to recognize that the efforts to date were somewhat overshadowed (derailed) by a one particular requirement that was given very high priority by the trustoverip/ctwg-sandbox researchers -- hoverText. While no one can disagree with the richness hoverText adds to READERS of ToIP Deliverables, this requirement at best SHOULD have been prioritized as a WISH not as a MUST HAVE. The justification for this position can be found in the ToIP Deliverables Process which went to great lengths to defined a set of document authoring requirements and to provide flexibility of tooling choice for ToIP Foundation members.

By placing so much emphasis on the hoverText derailment factor, the resulting solution ignored:

1. Multiple rendering format flexibility (.pdf, .md, .html)
2. ToIP themed and templated Authoring Tool Options

As a result, it is the opinion of this issue author (@vinomaster), that it would be very difficult for the ToIP Foundation to support the trustoverip/ctwg-sandbox solution approach.

Additionally, as author (@vinomaster) of this issue, the following factors SHOULD also be considered in the assessment of the trustoverip/ctwg-sandbox solution:

1. No Central Corpus: While tactical in nature, the copying of term .md files into each repo creates alot of duplication and reduces the value of ToIP curated terms because each deliverables repo task force could maintain its own version of terms in their repos. Thus, defeating the purpose of the CTWG.

2. Incomplete Tooling Proposal: The ToIP Foundation is not bound to a single tool and welcomes the opportunity to offer membership other authoring tools. However, such new tooling proposals SHOULD be considered as consistent packages with existing efforts that provide:

   • ToIP Theming
   • GitHub Template Repo funtionality
   • Familiar repo build and usage instructions

3. Avoidance of ToIP Process Ramifications: Process proposals SHOULD NOT ignore the impact they have on existing processes, assets and work-in-progress.

Tactical Solution

Imagine the basic tasks of a ToIP Foundation Author concerning document development:

1. Discovery: Find a term/concept definition
2. Submission: Propose a new term/concept definition
3. Usage: Refer to a term/concept definition

Let us assume the term SSI is defined in a CTWG file called ssi.md and that it complies with the data model prescribed by the trustoverip/ctwg-sandbox solution.

Alex, a ToIP Foundation Author, would desire to simply use a term-by-reference approach while he is writing his content using Markdown, the ToIP Foundation approved language.

The [SSI](http://ctwg-server.trustoverip.org/ssi/) community is cool.

While the above Usage model is feasible in all ToIP Authoring Tools, it is currently not feasible as it places a strategic dependency on the CTWG Process -- support for a RESTful web server.

However, a tactical solution is possible whereby Alex's repo would have a local file called glossary.md that contained all of his terms of interest.

Given a centralized repo based corpus of Markdown files in the data model prescribed by the trustoverip/ctwg-sandbox solution, we SHOULD be able to create a simple command-line tool in the trustoverip/concepts-and-terminology-wg repo whereby Alex could obtain on-demand a static glossary.md file that he could add to his repo.

make glossary tag={gswg,tswg}

This command-line tool would:

1. search all CTWG terms (.md files) for terms matching the desired tags
2. sort the results
3. generate a single markdown file from the data model complaint docs

Alex would then use use a local-term-by-reference approach

The [SSI](./glossary.md#ssi) community is cool.

and if he desired a change to any term he would follow the CTWG Submission processes and then rerun the command-line tool to update his local copy.

This approach COULD benefit from existing tools such as pandoc which is already used by the current set of ToIP Authoring Tools. However, this approach WILL REQUIRE a pre-processor to remove the data model metadata and to generate a glossary definition for each term from the associated source files (.md files).

This proposed approach has the following tactical benefits:

Objective	Pass/Fail Assessment	Comment
1. Definition of a data model for Terms and Concepts	Pass	Uses current CTWG proposed data model.
2. Curation process for Terms and Concepts	Pass	Proposal is decoupled from internal curation process of the CTWG members -- whatever it is and whenever it is produced.
3. Tool agnostic use of a CTWG corpus of terms and concepts	Pass	Loosely coupled from the document generation and rendering decisions a ToIP task forces may make relative to authoring tools. Thus, inline with ToIP Deliverables Process Requirements.

[vinomaster]

For additionally clarity, we could assume the strategic approach for the CTWG is to serve up a RESTful API for term access.

Additionally, we could assume that an alternative tactical approach exists whereby the CTWG creates repo enhancements for the ToIP versions of MkDocs and Spec-up. However, such an effort would be outside the expected scope of the CTWG charter and given the aforementioned shortage of volunteer developers it would be hard to justify.

Therefore the tactical proposal captured in this issue represents a path of least resistance example while enabling the CTWG members to focus on their true intentions the mental model for terms and concepts along with an associated curation process.

[vinomaster]

Proposed Pathway Forward

The CTWG eventually needs to define a roadmap to address delivering on its charter.

In the meantime, we need to establish a plan that will:

1. Enable ToIP Authors to perform the work of the Foundation.
2. Establish a well defined term/concept submission process and communicate it to the Foundation.
3. Establish a well defined and resourced term curation process.

Suggested steps towards success

Giving consideration to the proposal outlined herein, the we SHOULD tackle the following items with a degree of urgency:

1. Create data model spec with element definitions. This spec will evolve overtime. Focus on minimum viable to aid the Enablement ToIP Authors. This can be simply published in the WG GitHub repo or its associated repo wiki.
2. Create data model template for GitHub Issue Submission. This will be used in the GitHub Issue TYemplates.
3. Document (for example on the GitHub repo wiki) the 3 possible submission process options that were validated/demonstrated in October 2020. See Issue 24 for more details.
4. Document (for example on the GitHub repo wiki) a Curator process for daily injection of submissions into corpus of repo files
5. Document (for example on the GitHub repo wiki) the internal curator process
6. Develop the CTWG make commands for generating glossary.md
7. Define an initial set of terms for a WG such as GSWG to test the full end-to-end process.
8. Present full process to the ToIP Foundation.

Day in a life

Imagine how our hypothical ToIP Author, Alex, would work with the artifacts of this WG.

Persona

1. Alex is member of the GSWG
2. He must author the TSS0001
3. There is already an github repo for TSS0001
4. He would like to obtain from the "curators" in ToIP a glossary definitions
5. He has already cloned a local copy of his fork of the TSS0001 repo

Tactical Approach (as per proposal herein)

1. He forks the CTWG repo
2. He opens a terminal window
3. He clones his fork
4. He generates a new glossary

   make glossary tags=gswg
   

5. Copies the new glossary.md to his TSS0001 repo
6. He now begins to author his TSS document using the term-by-local-reference

   hello [world](./glossary.md#world)
   

7. He commits changes and submits a pull-request to the TSS0001 repo

Strategic Approach

1. He issues an API call to obtain a new glossary file

   <ctwg-server/generateGlossary?tags=gswg
   

2. Copies the new glossary.md to his TSS0001 repo
3. He now begins to author his TSS document using the term-by-local-reference

   hello [world](./glossary.md#world)
   

4. He commits changes and submits a pull-request to the TSS0001 repo

Data Model Bootstrap

We MUST establish a well defined term/concept submission process and communicate it to the Foundation.

We have already done significant investigation work. See ctwg-sandbox repo as well as work delivered in association with Issue 24.

If we combined (as an example) the data models used in those two efforts, we will have the basis for a data model spec that needs some refinement and documentation for element definitions.

For example:

id: action

title: "Action"

scopeid: essifLab

type: concept

typeid: action

stage: draft

hoverText: "Action --  something that is actually done/executed - by a single Actor (on behalf of a given Party), as a single operation in a specific context."

relatedTitles: <similar terms/concepts>

titleContext: <context to differentiate between related term usage>

## Definition
A distinct system of domain specific ledgers operated by decentralized peer nodes and associated with a DID Namespace. Governed by its own governance framework. See also Public Identity Utility.

## Short Description

An **Action** is something that is actually done/executed by a %%actor|actor%% in some context (i.e. in a specific place, at a specific time). During the time interval in which the action is executed, the actor may still execute other actions in other execution-contexts (multi-tasking). An action is executed on behalf of a specific party, which means that the primary guidance for executing the action, e.g. how to execute it, boundary conditions within which the execution must take place, etc., comes from a %%policy|policy%% that this party has established for actions of that kind. The actor is assumed to have appropriate access to that policy.

The %%Parties, Actors and Actions pattern|pattern-party-actor-action%% provides an overview of how this concept fits in with related concepts.

### Purpose

The ability to distinguish between (non)actions allows one to determine which (kinds of) %%actors|actor%% are capable of executing actions (e.g. by establishing that they have the competences required by the party), and as a consequence may be permitted and/or required to execute them. Also, this ability enables parties to determine the execution-policy, i.e. the set of rules, working-instructions, preferences and other guidance that actors should obey or comply with when executing an action on its behalf.


### Criterion

An **Action** is something that is done by an actor, can be considered a single operation, and is performed in a specific context, for or on behalf of a specific party, i.e. in accordance with the policy rules that this party has established for such actions.

## Tags

#ufwg, #gswg, #tswg, #bbu


### Related Concepts

<!--Link to any concepts that are similar but distinct, with a note about the relationship.-->

- OED defines Action as the fact or process of doing something, typically to achieve an aim ([OED](https://www.lexico.com/definition/action)), which is too generic for our purposes.

- %%actor|actor%%

- %%agent|agent%%


### Example Usage

- filling in a form and submitting it.

- cleaning a car.

Data Model Questions

1. Which element would be used to return the definition when generating a glossary.md.
2. What is the difference between Definition, Short Definition, HoverText elements? Can we prune here?
3. Are there any other tags we require besides what is covered here? If so , an issue and corresponding PR should be submitted against trustoverip/deliverables.