Fix GQM Links (#101)

jeffabailey · web-flow · commit 5837fe8f86a5 · 2025-05-12T19:29:46.000-07:00
* chore: move guidance to gqm_soexample README
fix: change root gqm links to prevent GitBook misinterpretation

* fix: add index.md to clean urls
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -10,7 +10,7 @@
   * [Comparing How Inner-Sourced Your Infra Is](infrastructure/assessment.md)
   * [Authors and Reviewers](infrastructure/authors.md)
 * [What, When and How to Measure](measuring/measuring.md)
-  * [Goals using Metrics](measuring/goals.md)
+  * [Goals using Metrics](measuring/goals_using_metrics.md)
     * [Use Goals, Questions, and Metrics](measuring/use_gqm.md)
       * [Goals](measuring/goals/index.md)
         * [Find InnerSource Projects](measuring/goals/find-projects.md)
@@ -27,7 +27,7 @@
   * [Areas of Analysis](measuring/areas.md)
   * [Goal-Question-Metric Approach](measuring/gqm.md)
   * [Strategy](measuring/strategy.md)
-  * [Examples of Interest](measuring/metrics.md)
+  * [Examples of Interest](measuring/examples.md)
   * [References](measuring/references.md)
   * [Authors and Reviewers](measuring/authors.md)
 * [Governance](governance/governance.md)
diff --git a/measuring/examples.md b/measuring/examples.md
@@ -0,0 +1 @@
+# Examples of Interest
diff --git a/measuring/goals/index.md b/measuring/goals/index.md
@@ -1,22 +1,21 @@
-# Goals
+# InnerSource Goals
 
-This section contains all the goals for measuring InnerSource projects.
+This directory contains the goals for measuring InnerSource success. Each goal is defined using the Goal-Question-Metric (GQM) approach.
 
 ## Available Goals
 
-- [Find InnerSource Projects](goals/find-projects.md) - Identify and discover InnerSource projects within the organization
-- [Reduce Duplication](goals/reduce-duplication.md) - Minimize code duplication through InnerSource practices
+1. [Find InnerSource Projects](find-projects.md)
+   - Make it easy for people to discover and use InnerSource projects
+   - Focuses on project discoverability and usage
 
-## How to Use
+2. [Reduce Duplication](reduce-duplication.md)
+   - Minimize redundant development efforts across the organization
+   - Encourages building software once and sharing it widely
 
-Each goal is defined in its own markdown file. The goals are used to:
-1. Define clear objectives for InnerSource initiatives
-2. Guide the selection of relevant questions
-3. Help determine appropriate metrics for measurement
+## Templates
 
-## Adding New Goals
+- [GQM Goal Template](gqm_goal_template.md) - Template for creating new goals using the GQM approach
 
-To add a new goal:
-1. Create a new markdown file in this directory
-2. Add a link to it in this README.md
-3. Update the GQM diagram by running the generator
+## Related Resources
+
+- [Back to the overall graph](../use_gqm.md)
diff --git a/measuring/goals_using_metrics.md b/measuring/goals_using_metrics.md
@@ -0,0 +1,47 @@
+Goals using Metrics
+===================
+
+This section aims at providing a strategy for your InnerSource metrics
+that help to understand the path from your initial process till a full
+InnerSource organization.
+
+It is important to remark that metrics useful for some organizations are
+not that useful in other contexts. This is similar to the open source
+projects where a project is not that similar to other in terms of
+governance, licenses, infrastructure or detailed process, but they are
+producing open source software and working as a community. This handbook
+has a similar goal, to detail how an ideal InnerSource project would
+be, but there are not two organizations using the same InnerSource
+approach.
+
+Thus, metrics useful for some contexts, for example technological
+organizations, might not apply to other context such as banks due to
+external factors such as legal regulations that are even different from
+country to country.
+
+In addition to all of this, when measuring InnerSource, there are three
+main purposes to use metrics: check on going work, lead process
+improvement[^5] and motivational aspects.
+
+-   **Check** on going work: this helps to understand where the
+    development is right now. To be aware of the status helps to
+    understand how fast things are changing when a new process is in the
+    pipeline. This also helps to go from A to B and even trying several
+    approaches to the same problem and have tests for this.
+
+-   **Lead** process improvement: InnerSource means a change in how
+    process works in the following. From a hierarchical way to a flatter
+    way of working, InnerSource needs indicators to help to determine
+    if that process improvement is properly working. And if this is not
+    working, then using another approach or apply other policies.
+
+-   **Motivational** aspects: InnerSource also means cultural change,
+    and this is not usually taken into account in other methodologies.
+    Indeed, this cultural change is identified in InnerSource as key.
+    This should be the type of actions that will help to migrate from a
+    traditional way of working to a more transparent and community-
+    oriented way to work. And metrics can help to lead this process.
+    First, to let developers know where they are and how their process
+    is working, but also to have some fun within the work and
+    competitions through challenges, hackathons and other measurable
+    activities that lead to a more community-oriented organizations.
diff --git a/measuring/gqm_example/README.md b/measuring/gqm_example/README.md
@@ -1,3 +1,17 @@
+## How Do I Add New Goals, Questions, and Metrics?
+
+Each goal, question, and metric is defined in its own markdown file. The goals, questions, and metrics are used to:
+
+1. Define clear objectives for InnerSource initiatives
+2. Guide the selection of relevant questions
+3. Help determine appropriate metrics for measurement
+
+## Adding New Goals, Questions, and Metrics
+
+To add a new goal, question, or metric:
+1. Create a new markdown file in the `goals`, `questions`, or `metrics` directory
+2. Update the GQM diagram by running the generator in the /scripts/gqm_gen directory
+
 # How Should I Format Goals Questions & Metrics?
 
 * [gqm_goal_template.md](../goals/gqm_goal_template.md)
diff --git a/measuring/metrics/index.md b/measuring/metrics/index.md
@@ -1,24 +1,33 @@
-# Metrics
+# InnerSource Metrics
 
-This section contains all the metrics used to measure InnerSource project questions.
+This directory contains the metrics used to measure InnerSource success. Each metric is defined using the Goal-Question-Metric (GQM) approach and provides specific ways to measure different aspects of InnerSource adoption and effectiveness.
 
 ## Available Metrics
 
-- [Code Contributions](metrics/code-contributions.md) - Measure the number and types of code contributions to InnerSource projects
-- [Contribution Distance](metrics/contribution-distance.md) - Measure how far contributions come from the original team
-- [Number of InnerSource repositories](metrics/number-of-innersource-repositories.md) - Track the total count of InnerSource repositories
-- [Usage Count](metrics/usage-count.md) - Measure how many times a component is used across the organization
+1. [Code Contributions](code-contributions.md)
+   - Measures non-owner commits to a project
+   - Tracks contribution diversity across people, business units, and time
+   - Unit: Ordinal number
 
-## How to Use
+2. [Contribution Distance](contribution-distance.md)
+   - Measures organizational distance between owning team and contributing team
+   - Indicates collaboration effectiveness and project impact
+   - Unit: Manager levels
 
-Each metric is defined in its own markdown file. The metrics are used to:
-1. Quantify answers to questions
-2. Track progress towards goals
-3. Provide actionable insights
+3. [Number of InnerSource Repositories](number-of-innersource-repositories.md)
+   - Tracks adoption of InnerSource practices across repositories
+   - Identifies repositories with InnerSource characteristics
+   - Unit: Number of repositories
 
-## Adding New Metrics
+4. [Usage Count](usage-count.md)
+   - Measures how many times an InnerSource project is used
+   - Tracks usage patterns across business units and time
+   - Unit: Ordinal number
 
-To add a new metric:
-1. Create a new markdown file in this directory
-2. Add a link to it in this README.md
-3. Update the GQM diagram by running the generator
+## Templates
+
+- [GQM Metric Template](gqm_metric_template.md) - Template for creating new metrics using the GQM approach
+
+## Related Resources
+
+- [Back to the overall graph](../use_gqm.md)
diff --git a/measuring/questions/index.md b/measuring/questions/index.md
@@ -1,23 +1,28 @@
-# Questions
+# InnerSource Questions
 
-This section contains all the questions used to measure InnerSource project goals.
+This directory contains the questions used in the Goal-Question-Metric (GQM) approach to measure InnerSource success. Each question helps evaluate different aspects of InnerSource adoption and effectiveness.
 
 ## Available Questions
 
-- [What is the InnerSource Adoption Trend?](questions/adoption-trend.md) - Track the growth and adoption of InnerSource practices over time
-- [Who contributes to the InnerSource project?](questions/who-contributes.md) - Identify and analyze the contributors to InnerSource projects
-- [Who Uses](questions/who-uses.md) - Track which teams and projects are using InnerSource components
+1. [What is the InnerSource adoption trend?](adoption-trend.md)
+   - Helps evaluate the growth and success of InnerSource programs
+   - Identifies potential program strategy issues or impediments
+   - Related metrics: Number of InnerSource repositories
 
-## How to Use
+2. [Who contributes to the InnerSource project?](who-contributes.md)
+   - Examines the diversity and scope of project contributions
+   - Covers various types of contributions (code, documentation, discussion)
+   - Related metrics: Code Contributions, Contribution Distance
 
-Each question is defined in its own markdown file. The questions are used to:
-1. Break down goals into measurable aspects
-2. Guide the selection of appropriate metrics
-3. Help evaluate progress towards goals
+3. [Who uses the InnerSource project?](who-uses.md)
+   - Tracks project adoption and usage patterns
+   - Covers different usage types (modules, APIs, UIs)
+   - Related metrics: Usage count
 
-## Adding New Questions
+## Templates
 
-To add a new question:
-1. Create a new markdown file in this directory
-2. Add a link to it in this README.md
-3. Update the GQM diagram by running the generator
+- [GQM Question Template](gqm_question_template.md) - Template for creating new questions using the GQM approach
+
+## Related Resources
+
+- [Back to the overall graph](../use_gqm.md)
diff --git a/measuring/use_gqm.md#goals b/measuring/use_gqm.md#goals
diff --git a/measuring/use_gqm.md#metrics b/measuring/use_gqm.md#metrics
diff --git a/measuring/use_gqm.md#questions b/measuring/use_gqm.md#questions
diff --git a/translations/gl/SUMMARY.md b/translations/gl/SUMMARY.md
@@ -10,7 +10,7 @@
   * [Compare canto ten de InnerSource a súa infraestrutura](infrastructure/assessment.md)
   * [Autoría e revisións](infrastructure/authors.md)
 * [Cales, cando e como empregalas](measuring/measuring.md)
-  * [Obxectivos no uso das métricas](measuring/goals.md)
+  * [Obxectivos no uso das métricas](measuring/goals_using_metrics.md)
   * [Áreas de análise](measuring/areas.md)
   * [Enfoque GQM (Obxectivo-Pregunta-Métrica)](measuring/gqm.md)
   * [Estratexia](measuring/strategy.md)
