configlet create usage (#488)

* Document configlet create in add-initial-exercises

* Add more documentation for new tracks

Author: ErikSchierboom

building/tracks/new/add-first-exercise.md

@@ -23,52 +23,95 @@ The "Hello, World!" exercise has some special rules applied to it:
 - It has no `prerequisites`
 - It has no `practices`
 
-### Updating the config
+### Determine file paths
 
-Start by adding an entry to the `exercises.practice` array in the top-level `config.json` file.
+The "Hello, World!" exercise (and indeed, _all_ exercises on Exercism) requires a specific set of files:
 
-```
-{
-  "exercises": {
-    "practice": [
-      {
-        "uuid": "",
-        "slug": "hello-world",
-        "name": "Hello World",
-        "practices": [],
-        "prerequisites": [],
-        "difficulty": 1
-      }
-    ]
-  }
+- Documentation: explain to the student what they need to do (can be auto-generated).
+- Metadata: provides Exercism with some metadata on the exercise (can be mostly auto-generated).
+- Test suite: verifies a solution's correctness (track-specific).
+- Stub implementation: provided a starting point for students (track-specific).
+- Example implementation: provides an example implementation that passes all the tests (track-specific).
+- Additional files: ensure that the tests can run (track-specific, optional).
+
+Before we can create the "Hello, World!" exercise, you need to make some decisions about the track-specific filenames and file paths (test suite, stub implementation, example implementation and any additional files).
+
+The rule of thumb is to use names that are idiomatic for the language.
+Where there are no strong preferences, prefer shallower directory structures.
+The example implementation will need to be identifiable by the CI script, so it's advisable to choose a generic basename that all exercises can use, e.g. `example`, `sample`, or `reference-solution`.
+
+#### Configuring file paths
+
+Having chosen the track-specific file paths, you should configure them in the `files` key in the root `config.json` file.
+The `files` key will serve as the template for all exercises, which allows any tooling (some of which we'll use in a second) to know where to look for files.
+You can use various placeholders to allow for easy configuring of the exercise's slug (`hello-world` in this case).
+
+##### Example
+
+If your track uses PascalCase for its files, the `files` key might look like this:
+
+```json
+"files": {
+  "solution": [
+    "%{pascal_slug}.cs"
+  ],
+  "test": [
+    "%{pascal_slug}Tests.cs"
+  ],
+  "example": [
+    ".meta/Example.cs"
+  ]
 }
 ```
 
-You can use the [Configlet][configlet] tool to get a UUID.
-Download Configlet by running `bin/fetch-configlet` from the root of the repository.
-Then generate a UUID using the `bin/configlet uuid` command.
+```exercism/note
+The example file(s) should be stored within the `.meta` directory.
+```
 
-### Generating required files
+For more information, check the [`files` key documentation](/docs/building/tracks/config-json#files).
 
-To implement the "Hello, World!" exercise, you'll need to create several files.
-Which files exactly is described in the [Practice Exercises documentation](/docs/building/tracks/practice-exercises).
+### Creating files
 
-Most of the files can be added automatically by running Configlet's `sync` command:
+Having specified the file path templates, you can then quickly scaffold the "Hello, World!" exercise's files by running the following commands from the track's root directory:
 
+```shell
+bin/fetch-configlet
+bin/configlet create --practice-exercise hello-world
 ```
-bin/configlet sync --update --yes --docs --metadata --exercise hello-world
-bin/configlet sync --update --tests include --exercise hello-world
-```
 
-In addition to the generated files, you will to create a test suite, a stub solution that serves as the starting point for the student, and a sample solution that passes all the tests to verify it is possible to solve the exercise (CI will verify this).
+### Implement exercise
+
+Once the scaffolded files have been created, you'll then have to:
+
+- Add tests to the tests file
+- Add an example implementation
+- Define the stub file's contents
+- Within the exercise's `.meta/config.json` file:
+  - Add the GitHub username of the exercise's authors to the `authors` key
+
+#### Add tests
+
+A key part of adding an exercise is adding tests.
+Rougly speaking, there are two options when implementing one of the above exercises:
+
+1. Implement the tests from scratch, using the test cases from the [exercise's `canonical-data.json`][canonical-data.json]
+2. Port the tests from another track's implementation (tip: go to `https://exercism.org/exercises/hello-world` to get an overview of which tracks have implemented a specific exercise).
+
+For the "Hello, World!" exercise, there will only be one test case, so either option should be fine.
+
+#### Add example implementation
+
+The example implementation file should contain the code requires to solve the tests.
+
+#### Define the stub
 
-In order to create these files, you need to make some decisions about filenames and file paths.
-The rule of thumb is to use names that are idiomatic for the language, and where there are no strong preferences prefer shallower directory structures.
-The sample solution will need to be identifiable by the CI script, so it's advisable to choose a generic basename that all exercises can use, e.g. `example`, `sample`, or `reference-solution`.
+The stub file should have an _almost_ working solution to the tests, but with the "Hello, World!" text replaced with "Goodbye, Mars!".
+Tip: just can copy-paste-modify the example solution.
 
-### Configuring the exercise
+### Update the exercise's author(s)
 
-One you've decided on the filenames and paths, edit the `exercises/practice/hello-world/.meta/config.json` file to reflect those choices.
-Also add your GitHub username to the `"authors"` array.
+Once you're done with the exercise, please add your your GitHub username to the `"authors"` array in the exercise's `.meta/config.json` file.
+This will ensure we correctly credit you with having created the exercise.
 
 [configlet]: /docs/building/configlet
+[canonical-data.json]: (https://github.com/exercism/problem-specifications/blob/main/exercises/hello-world/canonical-data.json)

building/tracks/new/add-initial-exercises.md

@@ -103,23 +103,46 @@ To make this all a bit more concrete, this is what a sample selection of initial
 
 ## Implement exercises
 
+### Scaffold exercise
+
 Having selected the exercises you want include in your track, the next step is to implement them.
-Each of the above-mentioned exercises has three bits of information:
+You can quickly scaffold a new Practice Exercise by running the following commands from the track's root directory:
+
+```shell
+bin/fetch-configlet
+bin/configlet create --practice-exercise <slug>
+```
+
+For more information, check the [`configlet create` docs](/docs/building/configlet/create)
+
+### Implement exercise
+
+Once the scaffolded files have been created, you'll then have to:
+
+- Add tests to the tests file
+- Add an example implementation
+- Define the stub file's contents
+- Within the exercise's `.meta/config.json` file:
+  - Add the GitHub username of the exercise's authors to the `authors` key
+- Within the track's `config.json` file:
+  - Check/update the exercise's difficulty
+  - Add concepts to the `practices` key (only required when the track has concept exercises)
+  - Add concepts to the `prerequisites` key (only required when the track has concept exercises)
 
-1. `description.md`: explains what the exercise is about (required)
-2. `metadata.toml`: metadata like the exercise's blurb (required)
-3. `canonical-data.json`: a set of input/output combinations that describe the behavior of the exercise (optional)
+#### Add tests
 
-There are two options when implementing one of the above exercises:
+A key part of adding an exercise is adding tests.
+Rougly speaking, there are two options when adding tests for one of the above exercises:
 
-1. Implement the exercise from scratch, using the test cases in the `canonical-data.json` file.
-2. Port an implementation of the exercise from another track.
+1. Implement the tests from scratch, using the test cases from the exercise's `canonical-data.json` file as found in the [problem-specifications repo][problem-specifications-exercises].
+2. Port the tests from another track's implementation (tip: go to `https://exercism.org/exercises/<slug>` to get an overview of which tracks have implemented a specific exercise).
 
 The second option can be particularly appealing, as it can give you results quickly.
 Keep in mind, though, that you should tweak the implementation to best fit your track.
 As an example, some tracks do not use classes but only work with functions.
 If your track usually works with objects though, you should adapt the implementation to what best fits your track.
 
+[problem-specifications-exercises]: https://github.com/exercism/problem-specifications/tree/main/exercises/
 [allergies]: https://github.com/exercism/problem-specifications/tree/main/exercises/allergies
 [alphametics]: https://github.com/exercism/problem-specifications/tree/main/exercises/alphametics
 [bank-account]: https://github.com/exercism/problem-specifications/tree/main/exercises/bank-account