Document configlet create (#485)

* configlet: document `create` command

* Add notes about using
'

Author: ErikSchierboom

building/configlet/README.md

@@ -36,6 +36,12 @@ Tests in this file are identified by their UUID and each test has a boolean valu
 
 You can find the details about how to sync the different parts of an exercise [here](/docs/building/configlet/sync).
 
+## Create files
+
+Configlet can be used to quickly scaffold files for a new approach, article or exercise.
+
+You can learn more about how to create these files [here](/docs/building/configlet/create).
+
 ## Generating UUIDs
 
 Exercises, tracks and concepts are identified by a UUID.

building/configlet/create.md

@@ -0,0 +1,95 @@
+# Configlet creating files
+
+When adding a new approach, article or exercise, you'll have to create files with very specific names.
+They also require configuration files to be added or updated.
+With the `create` command, [configlet](/docs/building/configlet) can do all this for you.
+
+## Usage
+
+The `create` command can be used to create the files required to add a new approach, article or exercise, as well as modify any configuration files.
+
+```shell
+configlet [global-options] create [command-options]
+
+Options for create:
+      --approach <slug>           The slug of the approach
+      --article <slug>            The slug of the article
+      --practice-exercise <slug>  The slug of the practice exercise
+      --concept-exercise <slug>   The slug of the concept exercise
+  -e, --exercise <slug>           Only operate on this exercise
+  -o, --offline                   Do not update the cached 'problem-specifications' data
+```
+
+## Create Practice Exercise
+
+To create a practice exercise, one has to specify its slug:
+
+```shell
+configlet create --practice-exercise collatz-conjecture
+```
+
+This will create the practice exercise's required files, as specified in the [Practice Exercises docs](/docs/building/tracks/practice-exercises).
+If the practice exercise is defined in the [Problem Specifications repo](https://github.com/exercism/problem-specifications/), configlet will sync the docs and metadata from there.
+
+Of course, this is just the first step towards creating an exercise.
+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)
+
+```exercism/note
+Some tracks have implemented an exercise/test _generator_, which is a tool that can generate the test file's contents based on the exercise's `canonical-data.json` found in the [Problem Specifications repo](https://github.com/exercism/problem-specifications/).
+Make sure to read the track's documentation to see if there is a generator that you can use.
+```
+
+## Create Concept Exercise
+
+To create a concept exercise, one has to specify its slug:
+
+```shell
+configlet create --concept-exercise bird-watcher
+```
+
+This will create the concept exercise's required files, as specified in the [Concept Exercises docs](/docs/building/tracks/concept-exercises).
+
+Of course, this is just the first step towards creating an exercise.
+You'll then have to:
+
+- Add tests to the tests file
+- Add an exemplar implementation
+- Define the stub file's contents
+- Write the introduction in `.docs/introduction.md`
+- Write the instructions in `.docs/instructions.md`
+- 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 `concepts` key
+  - Add concepts to the `prerequisites` key
+
+## Create Approach
+
+To create an approach's files, one has to specify the slug of the approach and its exercise:
+
+```shell
+configlet create --approach recursion --exercise collatz-conjecture
+```
+
+This will create the approach's required files, as specified in the [Approaches docs](/docs/building/tracks/approaches).
+
+## Create Article
+
+To create an article's files, one has to specify the slug of the article and its exercise:
+
+```shell
+configlet create --article performance --exercise collatz-conjecture
+```
+
+This will create the article's required files, as specified in the [Articles docs](/docs/building/tracks/articles).

building/tracks/concept-exercises.md

@@ -4,6 +4,17 @@
 The concepts taught by the concept exercises form a _syllabus_.
 For more information on how to design a syllabus, check the [syllabus documentation](/docs/building/tracks/syllabus).
 
+````exercism/note
+You can quickly scaffold a new Concept Exercise by running the following commands from the track's root directory:
+
+```shell
+bin/fetch-configlet
+bin/configlet create --concept-exercise <slug>
+```
+
+For more information, check the [`configlet create` docs](/docs/building/configlet/create)
+````
+
 ## Metadata
 
 Concept Exercise metadata is defined in the `exercises.concept` key in the [config.json file](/docs/building/tracks/config-json#concept-exercises). The metadata defines the exercise's UUID, slug and more.

building/tracks/practice-exercises.md

@@ -6,6 +6,17 @@ Interested in adding your first Practice Exercise to a track? Watch our walkthro
 
 [video:vimeo/906101866?h=2954ad331e]()
 
+````exercism/note
+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)
+````
+
 ## Metadata
 
 Practice Exercise metadata is defined in the `exercises.practice` key in the [config.json file](/docs/building/tracks/config-json). The metadata defines the exercise's UUID, slug and more.