updated instructions for generating diagram to address some issues I ran into

Author: JustinGOSSES

measuring/metrics/contribution_distance.md renamed to measuring/metrics/contribution-distance.md

@@ -9,3 +9,4 @@ There are many types of contributions - e.g. code, documentation, discussion, et
 | **Metric** | **How it answers the question** | **Gotchas** |
 | --- | --- | --- |
 | [Code Contributions](../metrics/code-contributions.md) | Each code contribution represents a contributor to the InnerSource project. | There are other types of contributions beyond code. |
+| [Contribution Distance](../metrics/contribution-distance.md) | Measures how far apart in the organization each InnerSource contribution is. | Depends on accurate information on the organization's hierarchy mapped to contributor identity. |

measuring/questions/who-contributes.md

@@ -2,11 +2,53 @@
 
 Creates a Mermaid diagram from Goal, Question, Metrics (GQM) Markdown files.
 
+The instructions below describe how to locally run 
+the script that builds the mermaid diagram. 
+A GitHub Actions will re-run this script at built time
+and regenerate the diagram, but it is good to run 
+locally to make sure it will build correctly.
+
+Be sure to also read the instructions in the 
+`measuring/use_gqm.md` file path.
+
+## Installation
+
+### Install mermaid CLI globally
+
+From this folder, follow instructions on the 
+[mermaid.js README](https://github.com/mermaid-js/mermaid-cli) to run in the terminal: 
+```
+npm install -g @mermaid-js/mermaid-cli
+```
+
+Install project specific node.js based on the package.json in this folder: 
+```
+npm install
+```
+
 ## Usage
 
 Builds the mermaid diagram and outputs it to stdout.
 
 ```bash
-npm install
-npm run --silent start
+npm run --silent start > gqm.mmd && mmdc --input gqm.md --output gqm.png
 ```
+
+Note that the file ending `.mmd` is not a typo. It is mermaid markdown file.
+
+This should generate a file called `gqm.png` or `gqm-1.png` in the same folder as this file.
+
+You will also end up with BOTH a `gqm.md` and a `gqm.mmd` file as the later is created upon running the script.
+
+## Files that impact the generation of the mermaid diagram
+
+Most of the diagram is generated by the `gqm.md` file but be sure to also 
+make changes in the files within the `measuring`, `questions`, and `goals` folders as appropriate. 
+You'll have to create a file for a new block and edit any file that mentions that new block. 
+For example, if you create a new metric, you'll want to create a new markdown file in the 
+metrics folder. Additionally, as there is an arrow that goes from that metric to a question, 
+you'll want to edit the table in the question file that talks to all the metrics that impact that question. A metric can be connected to one or more questions.
+
+### Warning
+Files that are referenced by the mermaid diagram must not use underscores `_` in their filenames. 
+Instead use hyphens `-`.

package-lock.json

@@ -0,0 +1,37 @@
+```mermaid
+graph LR;
+
+    subgraph GQM[Goals, Questions, Metrics]
+
+      find-projects.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//goals/find-projects.md'>Find InnerSource Projects</a>]
+    reduce-duplication.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//goals/reduce-duplication.md'>Reduce duplication</a>]
+    who-contributes.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//questions/who-contributes.md'>Who contributes to the InnerSource project?</a>]
+    who-uses.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//questions/who-uses.md'>Who uses the InnerSource project?</a>]
+    code-contributions.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//metrics/code-contributions.md'>Code contributions</a>]
+    contribution-distance.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//metrics/contribution-distance.md'>Contribution distance</a>]
+    usage-count.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//metrics/usage-count.md'>Usage count</a>]
+    find-projects.md-->who-uses.md
+    find-projects.md-->who-contributes.md
+    reduce-duplication.md-->who-uses.md
+    who-contributes.md-->code-contributions.md
+    who-contributes.md-->contribution-distance.md
+    who-uses.md-->usage-count.md
+  end
+      subgraph Legend
+        direction TB
+
+        goal[Goal]
+        question[Question]
+        metric[Metric]
+
+        classDef goals stroke:green,stroke-width:2px;
+        class goal,find-projects.md,reduce-duplication.md goals
+
+        classDef questions stroke:orange,stroke-width:2px;
+        class question,who-contributes.md,who-uses.md questions
+
+        classDef metrics stroke:purple,stroke-width:2px;
+        class metric,code-contributions.md,contribution-distance.md,usage-count.md metrics
+      end  
+  
+```

scripts/gqm_gen/README.md

@@ -0,0 +1,37 @@
+```mermaid
+graph LR;
+
+    subgraph GQM[Goals, Questions, Metrics]
+
+      find-projects.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//goals/find-projects.md'>Find InnerSource Projects</a>]
+    reduce-duplication.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//goals/reduce-duplication.md'>Reduce duplication</a>]
+    who-contributes.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//questions/who-contributes.md'>Who contributes to the InnerSource project?</a>]
+    who-uses.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//questions/who-uses.md'>Who uses the InnerSource project?</a>]
+    code-contributions.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//metrics/code-contributions.md'>Code contributions</a>]
+    contribution-distance.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//metrics/contribution-distance.md'>Contribution Distance</a>]
+    usage-count.md[<a href='https://github.com/InnerSourceCommons/managing-inner-source-projects/blob/main/measuring//metrics/usage-count.md'>Usage count</a>]
+    find-projects.md-->who-uses.md
+    find-projects.md-->who-contributes.md
+    reduce-duplication.md-->who-uses.md
+    who-contributes.md-->code-contributions.md
+    who-contributes.md-->contribution-distance.md
+    who-uses.md-->usage-count.md
+  end
+      subgraph Legend
+        direction TB
+
+        goal[Goal]
+        question[Question]
+        metric[Metric]
+
+        classDef goals stroke:green,stroke-width:2px;
+        class goal,find-projects.md,reduce-duplication.md goals
+
+        classDef questions stroke:orange,stroke-width:2px;
+        class question,who-contributes.md,who-uses.md questions
+
+        classDef metrics stroke:purple,stroke-width:2px;
+        class metric,code-contributions.md,contribution-distance.md,usage-count.md metrics
+      end  
+  
+```