Reorganise things

contributing/README.md

@@ -0,0 +1,4 @@
+# Contributing to Exercism
+
+This section of the docs looks at how to contribute to Exercism.
+It contains information specs for all various areas of Exercism as well as guides to things like becoming a maintainer and choosing a story for an exercise.

contributing/community/README.md

@@ -0,0 +1,3 @@
+# Community
+
+This section covers various things to know about the Exercism community, looking at how to be a good community member, and understanding the roles different people fulfil.

contributing/chestertons-fence.md → contributing/community/chestertons-fence.md

@@ -1,6 +1,6 @@
 # Chesterton's Fence
 
-Hello :wave:
+Hello 👋
 You're probably here because someone directed you to this post in response to you suggesting an idea about how Exercism could be improved.
 Before our team invests time into exploring your idea, they're hoping you'll read this and consider whether your idea might have been thought of before, what pitfalls it might contain.
 **By adding those considerations and potential pitfalls to your suggestion, and considering why your idea might not have already been implemented, you are likely to get a faster and more positive response.**
@@ -50,7 +50,7 @@ So firstly, what does it mean to "just call a command to run the tests".
 It means writing a script for each of the 52 languages on Exercism that can run the tests and check the outcome.
 That's a bit of effort, but doable.
 
-But it also means writing that script so that it runs on Windows, MacOSX and Linux --  in any and all possible versions/configurations. That's a lot (if not an unbounded) amount of work.
+But it also means writing that script so that it runs on Windows, MacOSX and Linux -- in any and all possible versions/configurations. That's a lot (if not an unbounded) amount of work.
 "Why does it have to be _every_ configuration?" you may ask?
 Well, because you're actively blocking someone from using Exercism unless they can run this script.
 That also means that it can never fail.

contributing/config.json

@@ -0,0 +1,71 @@
+[
+  {
+    "uuid": "7c7139b9-a228-4691-a4e4-a0c39a6dd615",
+    "section": "contributing",
+    "slug": "APEX",
+    "path": "contributing/README.md",
+    "title": "Contributing to Exercism",
+    "blurb": "An overview of how to contribte to Exercism"
+  },
+
+  {
+    "uuid": "d078e880-a732-4e39-998f-fbe7397fe677",
+    "slug": "contributing/community",
+    "path": "contributing/community/README.md",
+    "title": "Community",
+    "blurb": "Learn how Exercism's community works"
+  },
+  {
+    "uuid": "3487dacd-f6ca-4784-b93f-c4a5d023f051",
+    "slug": "contributing/community/administrators",
+    "path": "contributing/community/administrators.md",
+    "title": "Exercism Adminstrators",
+    "blurb": "Learn about Exercism's Administrators"
+  },
+  {
+    "uuid": "7e11a8f5-e6f8-49f1-ab0c-81427fa12c5c",
+    "slug": "contributing/community/being-a-good-member",
+    "path": "contributing/community/being-a-good-member.md",
+    "title": "Being a good community member",
+    "blurb": "Learn how to be a great member of the Exercism community"
+  },
+  {
+    "uuid": "55064dce-a51b-43d2-b8ce-9777d1f39528",
+    "slug": "contributing/community/chestertons-fence",
+    "path": "contributing/community/chestertons-fence.md",
+    "title": "Chesterton's Fence",
+    "blurb": "Learn how to express your ideas in suggestions in the best way"
+  },
+
+  {
+    "uuid": "d372e903-31fa-4918-a506-e3f939452828",
+    "slug": "contributing/configlet",
+    "path": "contributing/configlet/README.md",
+    "title": "Configlet",
+    "blurb": "The canonical specifications for everything on Exercism"
+  },
+  {
+    "uuid": "3cdd0fcd-8283-4f80-b16c-2ee089347120",
+    "slug": "contributing/configlet/uuid",
+    "path": "contributing/configlet/uuid.md",
+    "title": "configlet uuid"
+  },
+  {
+    "uuid": "dc118ace-041d-47f4-863c-2151e3b0e27c",
+    "slug": "contributing/configlet/sync",
+    "path": "contributing/configlet/sync.md",
+    "title": "configlet sync"
+  },
+  {
+    "uuid": "833996f1-271e-4fc0-b5c0-d349a1d715ab",
+    "slug": "contributing/configlet/lint",
+    "path": "contributing/configlet/lint.md",
+    "title": "configlet lint"
+  },
+  {
+    "uuid": "d8d9ff53-fe8f-4333-80c5-87517433cf7d",
+    "slug": "contributing/configlet/generating-documents",
+    "path": "contributing/configlet/generating-documents.md",
+    "title": "Generating Documents"
+  }
+]

anatomy/tracks/configlet/generating-documents.md → contributing/configlet/generating-documents.md

@@ -1,6 +1,6 @@
 # Configlet generating documents
 
-The secondary use of [configlet](./README.md) is generating documents.
+The secondary use of [configlet](../) is generating documents.
 
 ## Usage
 

anatomy/tracks/configlet/linting.md → contributing/configlet/lint.md

@@ -1,6 +1,6 @@
 # Linting
 
-The primary use of [configlet](./README.md) is linting: checking if a track's configuration files are properly structured - both syntactically and semantically. Misconfigured tracks may not sync correctly, may look wrong on the website, or may present a suboptimal user experience, so configlet's guards play an important part in maintaining the integrity of Exercism.
+The primary use of [configlet](../) is linting: checking if a track's configuration files are properly structured - both syntactically and semantically. Misconfigured tracks may not sync correctly, may look wrong on the website, or may present a suboptimal user experience, so configlet's guards play an important part in maintaining the integrity of Exercism.
 
 ## Usage
 

anatomy/tracks/configlet/uuids.md → contributing/configlet/uuid.md

@@ -1,6 +1,6 @@
 # Generating UUIDs
 
-Exercises, tracks and concepts are identified by a UUID. [configlet](./README.md) can generate new, valid UUIDs.
+Exercises, tracks and concepts are identified by a UUID. [configlet](../) can generate new, valid UUIDs.
 
 ## Usage
 

contributing/maintainers/README.md

@@ -0,0 +1,3 @@
+# Maintainers
+
+TODO

contributing/maintainers/becoming-a-maintainer.md

@@ -0,0 +1,3 @@
+# Becoming a maintainer
+
+TODO

contributing/standards/markdown.md → contributing/markdown/markdown.md

@@ -91,18 +91,20 @@ A quick way to distinguish between the two cases when it's unclear - if this is
 
 ## Special blocks (sometimes called admonitions)
 
-We support special types of blocks that can be added to documents to pull out commentary that doesn't fit with the main body of the text. 
+We support special types of blocks that can be added to documents to pull out commentary that doesn't fit with the main body of the text.
 They are similar to these examples, seen in the Julia docs:
 
 <img width="500" alt="Screenshot 2021-03-13 at 17 15 04" src="https://user-images.githubusercontent.com/286476/111038207-aca0bd00-841f-11eb-95fb-20a93943d3dd.png">
 
 We support three types of blocks:
+
 - **exercism/note:** Blocks that pull out some extra special information
 - **exercism/caution:** Things that people should know about or tread carefully with
 - **exercism/advanced:** Information that is only relevant for people who want to dig more deeply into something or are expected to have more advanced knowledge.
 
 All blocks are written using 4 tildes, in the form of:
-`````
+
+````
 ~~~~exercism/note
 Content goes here
 
@@ -111,7 +113,7 @@ You can include code:
 str = "Hello, World"
 ```
 ~~~~
-`````
+````
 
 (Note: You may also use backticks or other levels of tildes in exceptional circumstances)
 

contributing/tracks/stories/regex.stage-heralding.md → contributing/stories/regex.stage-heralding.md

@@ -9,9 +9,9 @@ You're given a list of speakers on your stage in advance and need to turn them i
 Since the list follows a particular formatting, you decide to write a short program that parses the list you're given using regular expressions (regex) and automatically generates the moderation cards.
 
 !!! note
-    This exercise is **not** about learning regular expressions.
-    It's about learning to use regex within $lang.
-    The hints contain a regular expression that you can use if you don't want to write one yourself.
+This exercise is **not** about learning regular expressions.
+It's about learning to use regex within $lang.
+The hints contain a regular expression that you can use if you don't want to write one yourself.
 
 The list you're given contains the following information for each talk:
 
@@ -33,7 +33,7 @@ Here, the title is `Speedrunning 101`, the speaker is called `Sasha Duda Krall`,
 The talk starts at `13:00`, there will be a Q&A starting at `13:20`, and the entire session ends at `13:30`.
 
 !!! note
-    Since names may contain regular dashes `-`, an en dash `–` is used to separate the speaker and talk name.
+Since names may contain regular dashes `-`, an en dash `–` is used to separate the speaker and talk name.
 
 The moderation card that your program should generate for that talk looks like this:
 
@@ -86,7 +86,7 @@ The corresponding cards are:
 - Kira's talk is called »Can dogs look up?«
 - Kira will answer your questions in the Q&A session at the end of the talk, starting at 21:05
 
-20:50 - 21:05 - 21:10 
+20:50 - 21:05 - 21:10
 ```
 
 A few things to note here:
@@ -97,15 +97,14 @@ A few things to note here:
   Note that it is not always appropriate to abbreviate someone's name like this, e.g. many Chinese names are better abbreviated by keeping the last name.
   However, the abbreviate-to-first-name rule happens to work fine for everyone speaking on this stage.
 
-
 ## Tasks
 
 ### 1. Write a regex that captures the information you need to generate the cards
 
 It's easiest to use a regex builder tool like [regex101](https://regex101.com/) or [RegExr](https://regexr.com/) to do this.
 
 !!! warning
-    Make sure to set the regex engine/flavour to $CHANGE_ME.
+Make sure to set the regex engine/flavour to $CHANGE_ME.
 
 If you're new to regex or struggle with creating an expression that captures all required information at once, you can also define several smaller expressions that capture parts of the information-
 

anatomy/track-tooling/analyzers/interface.md → contributing/tooling/analyzers/interface.md

@@ -37,14 +37,14 @@ The `analysis.json` file should be structured as followed:
 }
 ```
 
-
 ### `summary` (optional)
 
-The summary field is a text (not markdown) field that summarises the output. 
+The summary field is a text (not markdown) field that summarises the output.
 It might say something like "Your solution is nearly there - there's just two small changes you can make." or "The code works great, but there's a little bit of linting that needs doing.".
 This summary is rendered on the website above the comments.
 
 ### `comments`
+
 Comments are keys into `website-copy/automated-comments/`, e.g. [`ruby.general.explicit_return -> automated-comments/ruby/general/explicit_return.md`](https://github.com/exercism/website-copy/blob/47af5b309ac263629ca5c52904046f81e0cc8def/automated-comments/ruby/general/explicit_return.md).
 
 Then can be structured either as single pointer strings (e.g. the last example above) or using a JSON Object to specify the follow keys:
@@ -55,23 +55,24 @@ The pointer-string to a file in `website-copy`.
 
 #### `params` (optional)
 
-A JSON Object containing any params that should be interpolated during rendering. 
+A JSON Object containing any params that should be interpolated during rendering.
 For example, in the markdown file, you could write `Try %{variable_name} += 1 instead`, and then set `params` to `{ "variable_name": "foo"}` in order to substitute `%{variable_name}` for the actual variable that the student used.
 
-When using parameterised files, ensure to escape all uses of `%` by placing anther `%` in front of it. 
+When using parameterised files, ensure to escape all uses of `%` by placing anther `%` in front of it.
 e.g. `Try aim aim for 100%% of the tests passing`.
 
 #### `type` (optional)
+
 The following `type`s are valid:
 
 - `essential`: We will soft-block students until they have addressed this comment
 - `actionable`: Any comment that gives a specific instruction to a user to improve their solution
 - `informative`: Comments that give information, but do not necessarily expect students to use it. For example, in Ruby, if someone uses String Concatenation in TwoFer, we also tell them about String Formatting, but don't suggest that it is a better option.
-- `celebratory`: Comments that tell users they've done something right, either as a general comment on the solution, or on a technique. 
+- `celebratory`: Comments that tell users they've done something right, either as a general comment on the solution, or on a technique.
 
 Comments without a type field default to `informative `.
 
-Currently in the website, we soft-block on essential comments, encourage students to complete actionable comments before marking as complete on Practice Exercises (but not Concept Exercises), but don't suggest any action on `informative` or `celebratory`. 
+Currently in the website, we soft-block on essential comments, encourage students to complete actionable comments before marking as complete on Practice Exercises (but not Concept Exercises), but don't suggest any action on `informative` or `celebratory`.
 However, in the future we may choose to add emojis or indicators to other types, or group them seperately.
 
 ## Debugging

anatomy/track-tooling/representers/creating-from-scratch.md → contributing/tooling/representers/creating-from-scratch.md

@@ -10,4 +10,4 @@ These are the steps to get going:
 
 We have an incredibly friendly and supportive community who will be happy to help you as you work through this! If you get stuck, please speak to us on Slack or create new issues at [exercism/exercism][exercism-repo] as needed 🙂
 
-[exercism-repo]: https://github.com/exercism/exercism 
+[exercism-repo]: https://github.com/exercism/exercism

anatomy/track-tooling/test-runners/creating-from-scratch.md → contributing/tooling/test-runners/creating-from-scratch.md

@@ -8,6 +8,6 @@ These are the steps to get going:
 2. Scan the [contents of this directory](./) to ensure you are comfortable with the idea of creating an Test Runner.
 3. Open an issue at [exercism/exercism][exercism-repo] introducing yourself and telling us which language you'd like to create a Test Runner for.
 
-We have an incredibly friendly and supportive community who will be happy to help you as you work through this!  If you get stuck, please speak to us on Slack or create new issues at [exercism/exercism][exercism-repo] as needed 🙂
+We have an incredibly friendly and supportive community who will be happy to help you as you work through this! If you get stuck, please speak to us on Slack or create new issues at [exercism/exercism][exercism-repo] as needed 🙂
 
-[exercism-repo]: https://github.com/exercism/exercism 
+[exercism-repo]: https://github.com/exercism/exercism

anatomy/tracks/concept-exercises.md → contributing/tracks/concept-exercises.md

@@ -76,6 +76,7 @@ exercises
 
 We favor an "optimistic merging" approach to new exercises, where tracks can develop exercises in a "work in progress" state.
 The minimal valid state, which will pass configlet and allow you to merge is:
+
 - Valid entry in the track `config.json`, with the `status` set to `wip`.
 - A valid `.meta/config.json` file
 - The following files being present, although they may be empty:

anatomy/tracks/concepts.md → contributing/tracks/concepts.md

@@ -56,7 +56,7 @@ Here some examples of what could be covered.
 - Popular usages for a Concept
 - Common pitfalls in a Concept's use (e.g. failing to consider thread-safety)
 - Limitations on use that may catch out the unsuspecting developer
-- Alternative approaches addressed in other Concepts (e.g. the ••recursion** Concept might reference that the **Higher Order Functions** Concept offers an alternative approach to similar problems)
+- Alternative approaches addressed in other Concepts (e.g. the ••recursion** Concept might reference that the **Higher Order Functions\*\* Concept offers an alternative approach to similar problems)
 - Compromises made for ease of learning or to accommodate the Exercism environment, e.g. multiple classes in single file
 - Similar features with which the Concept may be confused
 - Performance characteristics and memory usage, when a common consideration within that language

mentoring/README.md

@@ -0,0 +1 @@
+# Mentoring on Exercism

mentoring/config.json

@@ -0,0 +1,10 @@
+[
+  {
+    "uuid": "0b9de7b0-9b64-4364-9318-44bcea76dac3",
+    "section": "mentoring",
+    "slug": "APEX",
+    "path": "mentoring/README.md",
+    "title": "Mentoring Guides",
+    "blurb": "Learn how to make the most of our mentoring on Exercism"
+  }
+]

using/config.json

@@ -0,0 +1,10 @@
+[
+  {
+    "uuid": "e6bcc4e9-31c0-4ddd-980d-8be1bd48ca40",
+    "section": "using",
+    "slug": "APEX",
+    "path": "using/README.md",
+    "title": "Using Exercism",
+    "blurb": "Learn how to make the most of our experience on Exercism"
+  }
+]