From dfe837bb4515ff0ffb42baf68bf7f55c8d1c89a8 Mon Sep 17 00:00:00 2001
From: Tim Austin <tim@neenjaw.com>
Date: Sat, 29 Jul 2023 05:35:08 -0600
Subject: [PATCH] Add concept map documentation (#449)

---
 building/config.json           |  7 +++++
 building/tracks/README.md      |  3 +++
 building/tracks/concept-map.md | 48 ++++++++++++++++++++++++++++++++++
 building/tracks/concepts.md    |  4 ++-
 4 files changed, 61 insertions(+), 1 deletion(-)
 create mode 100644 building/tracks/concept-map.md

diff --git a/building/config.json b/building/config.json
index 9302a3e9..266c1ceb 100644
--- a/building/config.json
+++ b/building/config.json
@@ -520,6 +520,13 @@
     "title": "Concepts",
     "blurb": ""
   },
+  {
+    "uuid": "0807db01-ce0e-4ac4-817b-7fe0a2366d01",
+    "slug": "tracks/concept-map",
+    "path": "building/tracks/concept-map.md",
+    "title": "Concept Map",
+    "blurb": ""
+  },
   {
     "uuid": "2a29f722-e70d-4679-81f8-bd6727fa9013",
     "slug": "tracks/config-json",
diff --git a/building/tracks/README.md b/building/tracks/README.md
index 7b94c7c8..ac2d64fc 100644
--- a/building/tracks/README.md
+++ b/building/tracks/README.md
@@ -11,6 +11,9 @@ The track's configuration and metadata are specified in the `config.json` file.
 All concept and practices exercises of a track involve _concepts_. These concepts are separate entities by themselves. Check the [documentation](/docs/building/tracks/concepts) for more information.
 
 The concepts taught in the track's concept exercises form a _syllabus_.
+The _syllabus_ is shown to students as a _concept map_.
+Check the [_concept map_ documentation](/docs/building/tracks/concept-map) to learn about building out the concept map for a _syllabus_.
+
 For more information on how to design a syllabus, check the [syllabus documentation](/docs/building/tracks/syllabus).
 
 ## Exercises
diff --git a/building/tracks/concept-map.md b/building/tracks/concept-map.md
new file mode 100644
index 00000000..e67a4cc6
--- /dev/null
+++ b/building/tracks/concept-map.md
@@ -0,0 +1,48 @@
+# Concept Map
+
+The concept map is one of the main methods to illustrate the progression that a student takes through the concept exercises.
+
+## Design Goals
+
+- Provide a meaningful concept map of ideas from simple to complex ideas.
+- Provide a pathway towards fluency in a language.
+- Illustrate the progression through the course contents.
+
+## Structure
+
+- Nodes
+  - Each concept is represented by a node on the concept map.
+  - Provide a quick reference with their style to indicate the degree of progression.
+    - Mastered: Concepts whose learning exercise and all associate practice exercise is complete.
+    - Complete: Concepts whose learning exercise is complete, but one or more practice exercise is not complete.
+    - Available: Concepts whose learning exercise has not been completed.
+    - Locked: Concepts whose learning exercise requires one or more pre-requisite exercise to be completed.
+- Paths
+  - Provide a relation of one concept to the next.
+  - Provide a relation indicating the building blocks of a concept back to the root.
+
+## Configuration
+
+The configuration of the concept map is determined by details of the [`config.json`](/docs/building/tracks/config-json) associated to a track.
+Specifically the specification of the concept exercises determines the shape and layout of the concept map.
+
+> You can view the code used to compute the concept map specification on GitHub: [Exercism/website: determine_concept_map_layout.rb][github-concept-code]
+
+A concept exercise specifies its prerequites and also the concept it teaches on completion.
+If we translate this to the terms of a [graph][wikipedia-graph]:
+- A concept represents a _vertex_ (also known as a _node_)
+- A concept exercise determines one or more _directed edges_ between two _vertices_ (_nodes_)
+
+It is important to note, not all edges that could be specified from the `config.json` appear in the result -- only the edges from the preceeding level are selected.
+
+```mermaid
+flowchart TD
+    Basics --> Integers
+    Integers --> Strings
+    Basics --Edge Removed--> Strings
+
+    linkStyle 2 stroke-width:2px,fill:none,stroke:red;
+```
+
+[github-concept-code]: https://github.com/exercism/website/blob/main/app/commands/track/determine_concept_map_layout.rb
+[wikipedia-graph]: https://en.wikipedia.org/wiki/Graph_(discrete_mathematics)
diff --git a/building/tracks/concepts.md b/building/tracks/concepts.md
index 6dcaa01b..830620e5 100644
--- a/building/tracks/concepts.md
+++ b/building/tracks/concepts.md
@@ -1,6 +1,8 @@
 # Concepts
 
-Concepts are the things that a programmer would need to understand to be fluent in a language. Concepts are taught by Concept Exercises and are used as prerequisites for Concept- _and_ Practice Exercises.
+Concepts are the things that a programmer would need to understand to be fluent in a language.
+Concepts are taught by Concept Exercises and are used as prerequisites for Concept- _and_ Practice Exercises.
+Concepts are placed on to a [_concept map_](/docs/building/tracks/concept-map) when displayed to the student.  
 
 ## Metadata