Add approaches docs (exercism#431)

kumargejara · Feb 15, 2023 · c2bbba5 · c2bbba5
1 parent 6a0731f
commit c2bbba5
Showing 1 changed file with 138 additions and 1 deletion.
diff --git a/building/tracks/practice-exercises.md b/building/tracks/practice-exercises.md
@@ -312,7 +312,144 @@ Note that:
 - The order of authors and contributors is not significant and has no meaning.
 - `language_versions` is a free-form string that tracks are free to use and interpret as they like.
 
-the articles
+### 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's approaches:
+
+- `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": "span",
+      "title": "Use Span<T>",
+      "blurb": "Use Span<T> to efficiently reverse a string.",
+      "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
+# Span
+
+```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);
+```
+
+This `Span<T>` approach uses a `for` loop.
+````
+
+---
+
+### 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 dig deeper page.
+
+Its number of lines must be <= 8.
+
+Check the [documentation](/docs/building/tracks/approaches) for more information on what should go in this file.
+
+#### 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: `.article/config.json`
+
+**Purpose:** Metadata for the articles
 
 **Presence:** Optional (required when an article exists)