Document approaches (#391)

Document approaches

Author: ErikSchierboom

building/config.json

@@ -555,6 +555,13 @@
     "title": "Deprecated Exercises",
     "blurb": "Learn why and how to deprecate an Exercism exercise"
   },
+  {
+    "uuid": "e5b94b50-cff3-4fcb-8fbf-4a247202da97",
+    "slug": "tracks/approaches",
+    "path": "building/tracks/approaches.md",
+    "title": "Approaches",
+    "blurb": "Learn how to write approaches for exercises"
+  },
   {
     "uuid": "8db530bb-e11b-4497-b088-5b4c997e09a2",
     "slug": "tracks/presentation",

building/tracks/README.md

@@ -20,6 +20,9 @@ Tracks have two types of exercises:
 - Concept exercises: they are designed to teach one or more concepts to a student. Check the [documentation](/docs/building/tracks/concept-exercises) for more information.
 - Practice exercises: they are designed to practice learned concepts. Check the [documentation](/docs/building/tracks/practice-exercises) for more information.
 
+Exercises can have approaches associated with them, which describe the different ways in which an exercise can be solved.
+Check the [documentation](/docs/building/tracks/approaches) for more information.
+
 ## Shared files
 
 Some files are not specific to individual exercises, but are instead applicable to _all_ exercises. Check the [documentation](/docs/building/tracks/shared-files) for more information.

building/tracks/approaches.md

@@ -0,0 +1,33 @@
+# Approaches
+
+Each exercise can have approaches associated with them, which describe the different ways in which an exercise can be solved.
+
+## Approach
+
+An approach should explore how an exercise can be solved a certain way.
+
+- Its contents should either:
+  - Explore an idiomatic approach
+  - Explore a non-idiomatic, but interesting approach
+  - Contain a meta discussion (e.g. comparing the performance of approaches)
+- Include code samples
+- Feel free to dig deep into the topic
+- Link to useful resources (e.g. documentation)
+
+## Approach overview
+
+- Give context to the problem
+  - Describe important points (e.g. gotchas) that apply to _all_ approaches
+- Discuss the most idiomatic approaches
+  - Each approach should show a snippet illustrating the approach
+  - Keep the content fairly high-level
+    - Link to the idiomatic approach for more information
+- Discuss how to choose between the approaches
+  - What are the trade-offs?
+  - Are some approaches better suited for specific use cases?
+
+## What exercises to write approaches for?
+
+In general, [Practice Exercises](/docs/building/tracks/practice-exercises) are more suitable to write approaches for, as they usually can be solved in multiple ways.
+
+For [Concept Exercises](/docs/building/tracks/concept-exercises), discussing the exemplar approach might be interesting. For example, you could show how the concept being taught makes certain code easier to write.

building/tracks/concept-exercises.md

@@ -30,7 +30,7 @@ Concept Exercise metadata is defined in the `exercises.concept` key in the [conf
 
 Each Concept Exercise has its own directory within the track's `exercises/concept` directory. The name of the Concept Exercise directory must match the `slug` property of the Concept Exercise, as defined in the [config.json file](/docs/building/tracks/config-json#concept-exercises).
 
-A Concept Exercise has three types of files:
+A Concept Exercise has four types of files:
 
 ### Documentation files
 
@@ -47,6 +47,15 @@ These files are _not_ presented to the student, but used to define metadata of t
 - `.meta/config.json`: contains meta information on the exercise (required)
 - `.meta/design.md`: describe the design of the exercise (required)
 
+### Approach files
+
+These files describe approaches for the exercise.
+
+- `.approaches/introduction.md`: introduction to the most common approaches for the exercise (optional)
+- `.approaches/config.json`: metadata for the approaches (optional)
+- `.approaches/<approach-slug>/content.md`: description of the approach (optional)
+- `.approaches/<approach-slug>/snippet.txt`: snippet showcasing the approach (optional)
+
 ### Exercise files
 
 The language-specific files, like the implementation and test files. The names of these files are track-specific.
@@ -62,6 +71,12 @@ The language-specific files, like the implementation and test files. The names o
 exercises
 └── concept
     └── cars-assemble
+        ├── .approaches
+        |   ├── performance (approach)
+        |   |   ├── content.md
+        |   |   └── snippet.txt
+        |   ├── config.json
+        |   └── introduction.md
         ├── .docs
         |   ├── introduction.md
         |   ├── instructions.md
@@ -347,6 +362,137 @@ Note that:
 
 ---
 
+### File: `.approaches/introduction.md`
+
+**Purpose:** Introduction to the most common approaches for the exercise
+
+**Presence:** Optional
+
+This file describes the most common approaches for the exercise.
+Check the [documentation](/docs/building/tracks/approaches) for more information on what should go in this file.
+
+#### Example
+
+````markdown
+# Introduction
+
+The key to this exercise is to deal with C# strings being immutable, which means that a `string`'s value cannot be changed.
+Therefore, to reverse a string you'll need to create a _new_ `string`.
+
+## Using LINQ
+
+```csharp
+public static string Reverse(string input)
+{
+    return new string(input.Reverse().ToArray());
+}
+```
+
+For more information, check the [LINQ approach][approach-linq].
+
+## Which approach to use?
+
+If readability is your primary concern (and it usually should be), the LINQ-based approach is hard to beat.
+````
+
+---
+
+### File: `.approaches/config.json`
+
+**Purpose:** Metadata for the approaches
+
+**Presence:** Optional (required when an approach introduction or approach exists)
+
+This file contains meta information on the exercise:
+
+- `introduction`: The GitHub username(s) of the exercise approach introduction's author(s) (optional)
+
+  - `authors`: The GitHub username(s) of the exercise approach introduction's author(s) (required)
+    - Including reviewers if their reviews substantially change the exercise approach introduction (to the extent where it feels like "you got there together")
+  - `contributors`: The GitHub username(s) of the exercise approach introduction's contributor(s) (optional)
+    - Including reviewers if their reviews are meaningful/actionable/actioned.
+
+- `approaches`: An array listing the detailed approaches (optional)
+  - `uuid`: a V4 UUID that uniquely identifies the approach. The UUID must be unique both within the track as well as across all tracks, and must never change
+  - `slug`: the approach's slug, which is a lowercased, kebab-case string. The slug must be unique across all approach slugs within the track. Its length must be <= 255.
+  - `title`: the approach's title. Its length must be <= 255.
+  - `blurb`: A short description of this approach. Its length must be <= 350. Markdown is _not_ supported (required)
+  - `authors`: The GitHub username(s) of the exercise approach's author(s) (required)
+    - Including reviewers if their reviews substantially change the exercise approach (to the extent where it feels like "you got there together")
+  - `contributors`: The GitHub username(s) of the exercise approach's contributor(s) (optional)
+    - Including reviewers if their reviews are meaningful/actionable/actioned.
+
+#### Example
+
+```json
+{
+  "introduction": {
+    "authors": ["erikschierboom"]
+  },
+  "approaches": [
+    {
+      "uuid": "448fb2b4-18ab-4e55-aa54-ad4ed6d5f7f6",
+      "slug": "performance",
+      "title": "Optimizing performance",
+      "blurb": "Explore how to most efficiently reverse a string and what the trade-offs are.",
+      "authors": ["erikschierboom"]
+    }
+  ]
+}
+```
+
+---
+
+### File: `.approaches/<approach-slug>/content.md`
+
+**Purpose:** Detailed description of the approach
+
+**Presence:** Optional (required for approaches)
+
+This file contains a detailed description of the approach.
+Check the [documentation](/docs/building/tracks/approaches) for more information on what should go in this file.
+
+#### Example
+
+```markdown
+# Performance
+
+In this document, we'll find out which approach is the most performant one.
+
+## Benchmark results
+
+| Method |      Mean |     Error |    StdDev |    Median | Allocated |
+| -----: | --------: | --------: | --------: | --------: | --------: |
+|   Linq | 29.133 ns | 0.5865 ns | 0.5486 ns | 28.984 ns |      80 B |
+|  Array |  4.806 ns | 0.4999 ns | 1.4739 ns |  3.967 ns |         - |
+```
+
+---
+
+### File: `.approaches/<approach-slug>/snippet.txt`
+
+**Purpose:** Snippet showcasing the approach
+
+**Presence:** Optional (required for approaches)
+
+This file contains a small snippet that showcases the approach.
+The snippet is shown on an exercise's approaches overview page.
+
+Its number of lines must be <= 8.
+
+#### Example
+
+```csharp
+Span<char> chars = stackalloc char[input.Length];
+for (var i = 0; i < input.Length; i++)
+{
+    chars[input.Length - 1 - i] = input[i];
+}
+return new string(chars);
+```
+
+---
+
 ### File: Stub implementation
 
 **Purpose:** Provide a starting point for students.