From d1b63e3d9ece0f6231e150f51ba8fc86dd94edc5 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A1s=20B=20Nagy?=
 <20251272+BNAndras@users.noreply.github.com>
Date: Sun, 29 Sep 2024 11:20:01 -0700
Subject: [PATCH] Sync docs and metadata (#771)

---
 .../practice/accumulate/.meta/config.json     |  2 +-
 .../practice/acronym/.docs/instructions.md    | 10 ++--
 .../practice/allergies/.docs/instructions.md  |  2 +-
 .../practice/anagram/.docs/instructions.md    |  6 +--
 .../practice/anagram/.docs/introduction.md    | 12 +++++
 .../binary-search-tree/.meta/config.json      |  3 +-
 .../binary-search/.docs/instructions.md       |  2 +-
 .../practice/bowling/.docs/instructions.md    |  6 +--
 .../circular-buffer/.docs/instructions.md     | 48 +++++++++++------
 exercises/practice/clock/.meta/config.json    |  3 +-
 .../flatten-array/.docs/instructions.md       |  2 +-
 .../practice/hamming/.docs/instructions.md    | 10 ++--
 .../practice/hello-world/.meta/config.json    |  2 +-
 .../practice/isogram/.docs/instructions.md    |  2 +-
 .../practice/list-ops/.docs/instructions.md   | 18 ++++---
 exercises/practice/luhn/.docs/instructions.md |  3 +-
 .../matching-brackets/.docs/instructions.md   |  3 +-
 .../matching-brackets/.docs/introduction.md   |  8 +++
 .../pascals-triangle/.docs/instructions.md    | 27 ++++++++--
 .../pascals-triangle/.docs/introduction.md    | 22 ++++++++
 .../perfect-numbers/.docs/instructions.md     | 53 ++++++++++++-------
 .../phone-number/.docs/instructions.md        | 10 ++--
 .../practice/pig-latin/.docs/instructions.md  |  4 +-
 .../practice/poker/.docs/instructions.md      |  2 +-
 exercises/practice/poker/.meta/config.json    |  2 +-
 .../protein-translation/.docs/instructions.md | 20 +++----
 .../pythagorean-triplet/.meta/config.json     |  2 +-
 .../queen-attack/.docs/instructions.md        | 20 +++----
 .../practice/raindrops/.meta/config.json      |  2 +-
 .../rotational-cipher/.docs/instructions.md   |  4 +-
 exercises/practice/say/.docs/instructions.md  |  2 -
 .../scale-generator/.docs/instructions.md     | 20 +++----
 .../practice/series/.docs/instructions.md     |  4 +-
 .../simple-cipher/.docs/instructions.md       |  6 +--
 .../practice/space-age/.docs/instructions.md  | 31 ++++++-----
 .../practice/space-age/.docs/introduction.md  | 20 +++++++
 exercises/practice/strain/.meta/config.json   |  4 +-
 .../practice/transpose/.meta/config.json      |  2 +-
 .../practice/wordy/.docs/instructions.md      |  2 +-
 39 files changed, 258 insertions(+), 143 deletions(-)
 create mode 100644 exercises/practice/anagram/.docs/introduction.md
 create mode 100644 exercises/practice/matching-brackets/.docs/introduction.md
 create mode 100644 exercises/practice/pascals-triangle/.docs/introduction.md
 create mode 100644 exercises/practice/space-age/.docs/introduction.md

diff --git a/exercises/practice/accumulate/.meta/config.json b/exercises/practice/accumulate/.meta/config.json
index ec8e30056..a0c263257 100644
--- a/exercises/practice/accumulate/.meta/config.json
+++ b/exercises/practice/accumulate/.meta/config.json
@@ -26,5 +26,5 @@
   },
   "blurb": "Implement the `accumulate` operation, which, given a collection and an operation to perform on each element of the collection, returns a new collection containing the result of applying that operation to each element of the input collection.",
   "source": "Conversation with James Edward Gray II",
-  "source_url": "https://twitter.com/jeg2"
+  "source_url": "http://graysoftinc.com/"
 }
diff --git a/exercises/practice/acronym/.docs/instructions.md b/exercises/practice/acronym/.docs/instructions.md
index c62fc3e85..133bd2cbb 100644
--- a/exercises/practice/acronym/.docs/instructions.md
+++ b/exercises/practice/acronym/.docs/instructions.md
@@ -10,8 +10,8 @@ Punctuation is handled as follows: hyphens are word separators (like whitespace)
 
 For example:
 
-|Input|Output|
-|-|-|
-|As Soon As Possible|ASAP|
-|Liquid-crystal display|LCD|
-|Thank George It's Friday!|TGIF|
+| Input                     | Output |
+| ------------------------- | ------ |
+| As Soon As Possible       | ASAP   |
+| Liquid-crystal display    | LCD    |
+| Thank George It's Friday! | TGIF   |
diff --git a/exercises/practice/allergies/.docs/instructions.md b/exercises/practice/allergies/.docs/instructions.md
index a13949209..daf8cfde2 100644
--- a/exercises/practice/allergies/.docs/instructions.md
+++ b/exercises/practice/allergies/.docs/instructions.md
@@ -22,6 +22,6 @@ Now, given just that score of 34, your program should be able to say:
 - Whether Tom is allergic to any one of those allergens listed above.
 - All the allergens Tom is allergic to.
 
-Note: a given score may include allergens **not** listed above (i.e.  allergens that score 256, 512, 1024, etc.).
+Note: a given score may include allergens **not** listed above (i.e. allergens that score 256, 512, 1024, etc.).
 Your program should ignore those components of the score.
 For example, if the allergy score is 257, your program should only report the eggs (1) allergy.
diff --git a/exercises/practice/anagram/.docs/instructions.md b/exercises/practice/anagram/.docs/instructions.md
index 7d1c8283e..a7298485b 100644
--- a/exercises/practice/anagram/.docs/instructions.md
+++ b/exercises/practice/anagram/.docs/instructions.md
@@ -1,9 +1,9 @@
 # Instructions
 
-An anagram is a rearrangement of letters to form a new word: for example `"owns"` is an anagram of `"snow"`.
-A word is not its own anagram: for example, `"stop"` is not an anagram of `"stop"`.
+Your task is to, given a target word and a set of candidate words, to find the subset of the candidates that are anagrams of the target.
 
-Given a target word and a set of candidate words, this exercise requests the anagram set: the subset of the candidates that are anagrams of the target.
+An anagram is a rearrangement of letters to form a new word: for example `"owns"` is an anagram of `"snow"`.
+A word is _not_ its own anagram: for example, `"stop"` is not an anagram of `"stop"`.
 
 The target and candidates are words of one or more ASCII alphabetic characters (`A`-`Z` and `a`-`z`).
 Lowercase and uppercase characters are equivalent: for example, `"PoTS"` is an anagram of `"sTOp"`, but `StoP` is not an anagram of `sTOp`.
diff --git a/exercises/practice/anagram/.docs/introduction.md b/exercises/practice/anagram/.docs/introduction.md
new file mode 100644
index 000000000..1acbdf00b
--- /dev/null
+++ b/exercises/practice/anagram/.docs/introduction.md
@@ -0,0 +1,12 @@
+# Introduction
+
+At a garage sale, you find a lovely vintage typewriter at a bargain price!
+Excitedly, you rush home, insert a sheet of paper, and start typing away.
+However, your excitement wanes when you examine the output: all words are garbled!
+For example, it prints "stop" instead of "post" and "least" instead of "stale."
+Carefully, you try again, but now it prints "spot" and "slate."
+After some experimentation, you find there is a random delay before each letter is printed, which messes up the order.
+You now understand why they sold it for so little money!
+
+You realize this quirk allows you to generate anagrams, which are words formed by rearranging the letters of another word.
+Pleased with your finding, you spend the rest of the day generating hundreds of anagrams.
diff --git a/exercises/practice/binary-search-tree/.meta/config.json b/exercises/practice/binary-search-tree/.meta/config.json
index 627751f4f..e05f518ea 100644
--- a/exercises/practice/binary-search-tree/.meta/config.json
+++ b/exercises/practice/binary-search-tree/.meta/config.json
@@ -20,6 +20,5 @@
     ]
   },
   "blurb": "Insert and search for numbers in a binary tree.",
-  "source": "Josh Cheek",
-  "source_url": "https://twitter.com/josh_cheek"
+  "source": "Josh Cheek"
 }
diff --git a/exercises/practice/binary-search/.docs/instructions.md b/exercises/practice/binary-search/.docs/instructions.md
index aa1946cfb..12f4358eb 100644
--- a/exercises/practice/binary-search/.docs/instructions.md
+++ b/exercises/practice/binary-search/.docs/instructions.md
@@ -11,7 +11,7 @@ Binary search only works when a list has been sorted.
 
 The algorithm looks like this:
 
-- Find the middle element of a *sorted* list and compare it with the item we're looking for.
+- Find the middle element of a _sorted_ list and compare it with the item we're looking for.
 - If the middle element is our item, then we're done!
 - If the middle element is greater than our item, we can eliminate that element and all the elements **after** it.
 - If the middle element is less than our item, we can eliminate that element and all the elements **before** it.
diff --git a/exercises/practice/bowling/.docs/instructions.md b/exercises/practice/bowling/.docs/instructions.md
index ddce7ee48..60ccad1b6 100644
--- a/exercises/practice/bowling/.docs/instructions.md
+++ b/exercises/practice/bowling/.docs/instructions.md
@@ -23,9 +23,9 @@ There are three cases for the tabulation of a frame.
 
 Here is a three frame example:
 
-| Frame 1         | Frame 2       | Frame 3                |
-| :-------------: |:-------------:| :---------------------:|
-| X (strike)      | 5/ (spare)    | 9 0 (open frame)       |
+|  Frame 1   |  Frame 2   |     Frame 3      |
+| :--------: | :--------: | :--------------: |
+| X (strike) | 5/ (spare) | 9 0 (open frame) |
 
 Frame 1 is (10 + 5 + 5) = 20
 
diff --git a/exercises/practice/circular-buffer/.docs/instructions.md b/exercises/practice/circular-buffer/.docs/instructions.md
index 3487a0f61..2ba1fda2a 100644
--- a/exercises/practice/circular-buffer/.docs/instructions.md
+++ b/exercises/practice/circular-buffer/.docs/instructions.md
@@ -4,39 +4,55 @@ A circular buffer, cyclic buffer or ring buffer is a data structure that uses a
 
 A circular buffer first starts empty and of some predefined length.
 For example, this is a 7-element buffer:
-<!-- prettier-ignore -->
-    [ ][ ][ ][ ][ ][ ][ ]
+
+```text
+[ ][ ][ ][ ][ ][ ][ ]
+```
 
 Assume that a 1 is written into the middle of the buffer (exact starting location does not matter in a circular buffer):
-<!-- prettier-ignore -->
-    [ ][ ][ ][1][ ][ ][ ]
+
+```text
+[ ][ ][ ][1][ ][ ][ ]
+```
 
 Then assume that two more elements are added — 2 & 3 — which get appended after the 1:
-<!-- prettier-ignore -->
-    [ ][ ][ ][1][2][3][ ]
+
+```text
+[ ][ ][ ][1][2][3][ ]
+```
 
 If two elements are then removed from the buffer, the oldest values inside the buffer are removed.
 The two elements removed, in this case, are 1 & 2, leaving the buffer with just a 3:
-<!-- prettier-ignore -->
-    [ ][ ][ ][ ][ ][3][ ]
+
+```text
+[ ][ ][ ][ ][ ][3][ ]
+```
 
 If the buffer has 7 elements then it is completely full:
-<!-- prettier-ignore -->
-    [5][6][7][8][9][3][4]
+
+```text
+[5][6][7][8][9][3][4]
+```
 
 When the buffer is full an error will be raised, alerting the client that further writes are blocked until a slot becomes free.
 
 When the buffer is full, the client can opt to overwrite the oldest data with a forced write.
 In this case, two more elements — A & B — are added and they overwrite the 3 & 4:
-<!-- prettier-ignore -->
-    [5][6][7][8][9][A][B]
+
+```text
+[5][6][7][8][9][A][B]
+```
 
 3 & 4 have been replaced by A & B making 5 now the oldest data in the buffer.
 Finally, if two elements are removed then what would be returned is 5 & 6 yielding the buffer:
-<!-- prettier-ignore -->
-    [ ][ ][7][8][9][A][B]
+
+```text
+[ ][ ][7][8][9][A][B]
+```
 
 Because there is space available, if the client again uses overwrite to store C & D then the space where 5 & 6 were stored previously will be used not the location of 7 & 8.
 7 is still the oldest element and the buffer is once again full.
-<!-- prettier-ignore -->
-    [C][D][7][8][9][A][B]
+
+```text
+[C][D][7][8][9][A][B]
+```
diff --git a/exercises/practice/clock/.meta/config.json b/exercises/practice/clock/.meta/config.json
index 27512f701..5911a4d77 100644
--- a/exercises/practice/clock/.meta/config.json
+++ b/exercises/practice/clock/.meta/config.json
@@ -24,6 +24,5 @@
     ]
   },
   "blurb": "Implement a clock that handles times without dates.",
-  "source": "Pairing session with Erin Drummond",
-  "source_url": "https://twitter.com/ebdrummond"
+  "source": "Pairing session with Erin Drummond"
 }
diff --git a/exercises/practice/flatten-array/.docs/instructions.md b/exercises/practice/flatten-array/.docs/instructions.md
index 51bea6790..89dacfa32 100644
--- a/exercises/practice/flatten-array/.docs/instructions.md
+++ b/exercises/practice/flatten-array/.docs/instructions.md
@@ -2,7 +2,7 @@
 
 Take a nested list and return a single flattened list with all values except nil/null.
 
-The challenge is to write a function that accepts an arbitrarily-deep nested list-like structure and returns a flattened structure without any nil/null values.
+The challenge is to take an arbitrarily-deep nested list-like structure and produce a flattened structure without any nil/null values.
 
 For example:
 
diff --git a/exercises/practice/hamming/.docs/instructions.md b/exercises/practice/hamming/.docs/instructions.md
index 020fdd02d..b9ae6efc5 100644
--- a/exercises/practice/hamming/.docs/instructions.md
+++ b/exercises/practice/hamming/.docs/instructions.md
@@ -1,6 +1,6 @@
 # Instructions
 
-Calculate the Hamming Distance between two DNA strands.
+Calculate the Hamming distance between two DNA strands.
 
 Your body is made up of cells that contain DNA.
 Those cells regularly wear out and need replacing, which they achieve by dividing into daughter cells.
@@ -9,18 +9,18 @@ In fact, the average human body experiences about 10 quadrillion cell divisions
 When cells divide, their DNA replicates too.
 Sometimes during this process mistakes happen and single pieces of DNA get encoded with the incorrect information.
 If we compare two strands of DNA and count the differences between them we can see how many mistakes occurred.
-This is known as the "Hamming Distance".
+This is known as the "Hamming distance".
 
-We read DNA using the letters C,A,G and T.
+We read DNA using the letters C, A, G and T.
 Two strands might look like this:
 
     GAGCCTACTAACGGGAT
     CATCGTAATGACGGCCT
     ^ ^ ^  ^ ^    ^^
 
-They have 7 differences, and therefore the Hamming Distance is 7.
+They have 7 differences, and therefore the Hamming distance is 7.
 
-The Hamming Distance is useful for lots of things in science, not just biology, so it's a nice phrase to be familiar with :)
+The Hamming distance is useful for lots of things in science, not just biology, so it's a nice phrase to be familiar with :)
 
 ## Implementation notes
 
diff --git a/exercises/practice/hello-world/.meta/config.json b/exercises/practice/hello-world/.meta/config.json
index 20938d569..1fecc872d 100644
--- a/exercises/practice/hello-world/.meta/config.json
+++ b/exercises/practice/hello-world/.meta/config.json
@@ -23,7 +23,7 @@
       ".meta/Sources/HelloWorld/HelloWorldExample.swift"
     ]
   },
-  "blurb": "The classical introductory exercise. Just say \"Hello, World!\".",
+  "blurb": "Exercism's classic introductory exercise. Just say \"Hello, World!\".",
   "source": "This is an exercise to introduce users to using Exercism",
   "source_url": "https://en.wikipedia.org/wiki/%22Hello,_world!%22_program"
 }
diff --git a/exercises/practice/isogram/.docs/instructions.md b/exercises/practice/isogram/.docs/instructions.md
index 5e4884476..2e8df851a 100644
--- a/exercises/practice/isogram/.docs/instructions.md
+++ b/exercises/practice/isogram/.docs/instructions.md
@@ -11,4 +11,4 @@ Examples of isograms:
 - downstream
 - six-year-old
 
-The word *isograms*, however, is not an isogram, because the s repeats.
+The word _isograms_, however, is not an isogram, because the s repeats.
diff --git a/exercises/practice/list-ops/.docs/instructions.md b/exercises/practice/list-ops/.docs/instructions.md
index d34533387..ebc5dffed 100644
--- a/exercises/practice/list-ops/.docs/instructions.md
+++ b/exercises/practice/list-ops/.docs/instructions.md
@@ -7,11 +7,13 @@ Implement a series of basic list operations, without using existing functions.
 
 The precise number and names of the operations to be implemented will be track dependent to avoid conflicts with existing names, but the general operations you will implement include:
 
-- `append` (*given two lists, add all items in the second list to the end of the first list*);
-- `concatenate` (*given a series of lists, combine all items in all lists into one flattened list*);
-- `filter` (*given a predicate and a list, return the list of all items for which `predicate(item)` is True*);
-- `length` (*given a list, return the total number of items within it*);
-- `map` (*given a function and a list, return the list of the results of applying `function(item)` on all items*);
-- `foldl` (*given a function, a list, and initial accumulator, fold (reduce) each item into the accumulator from the left using `function(accumulator, item)`*);
-- `foldr` (*given a function, a list, and an initial accumulator, fold (reduce) each item into the accumulator from the right using `function(item, accumulator)`*);
-- `reverse` (*given a list, return a list with all the original items, but in reversed order*);
+- `append` (_given two lists, add all items in the second list to the end of the first list_);
+- `concatenate` (_given a series of lists, combine all items in all lists into one flattened list_);
+- `filter` (_given a predicate and a list, return the list of all items for which `predicate(item)` is True_);
+- `length` (_given a list, return the total number of items within it_);
+- `map` (_given a function and a list, return the list of the results of applying `function(item)` on all items_);
+- `foldl` (_given a function, a list, and initial accumulator, fold (reduce) each item into the accumulator from the left_);
+- `foldr` (_given a function, a list, and an initial accumulator, fold (reduce) each item into the accumulator from the right_);
+- `reverse` (_given a list, return a list with all the original items, but in reversed order_).
+
+Note, the ordering in which arguments are passed to the fold functions (`foldl`, `foldr`) is significant.
diff --git a/exercises/practice/luhn/.docs/instructions.md b/exercises/practice/luhn/.docs/instructions.md
index 8cbe791fc..49934c106 100644
--- a/exercises/practice/luhn/.docs/instructions.md
+++ b/exercises/practice/luhn/.docs/instructions.md
@@ -22,7 +22,8 @@ The first step of the Luhn algorithm is to double every second digit, starting f
 We will be doubling
 
 ```text
-4_3_ 3_9_ 0_4_ 6_6_
+4539 3195 0343 6467
+↑ ↑  ↑ ↑  ↑ ↑  ↑ ↑  (double these)
 ```
 
 If doubling the number results in a number greater than 9 then subtract 9 from the product.
diff --git a/exercises/practice/matching-brackets/.docs/instructions.md b/exercises/practice/matching-brackets/.docs/instructions.md
index 544daa968..ea1708423 100644
--- a/exercises/practice/matching-brackets/.docs/instructions.md
+++ b/exercises/practice/matching-brackets/.docs/instructions.md
@@ -1,4 +1,5 @@
 # Instructions
 
 Given a string containing brackets `[]`, braces `{}`, parentheses `()`, or any combination thereof, verify that any and all pairs are matched and nested correctly.
-The string may also contain other characters, which for the purposes of this exercise should be ignored.
+Any other characters should be ignored.
+For example, `"{what is (42)}?"` is balanced and `"[text}"` is not.
diff --git a/exercises/practice/matching-brackets/.docs/introduction.md b/exercises/practice/matching-brackets/.docs/introduction.md
new file mode 100644
index 000000000..0618221b2
--- /dev/null
+++ b/exercises/practice/matching-brackets/.docs/introduction.md
@@ -0,0 +1,8 @@
+# Introduction
+
+You're given the opportunity to write software for the Bracketeer™, an ancient but powerful mainframe.
+The software that runs on it is written in a proprietary language.
+Much of its syntax is familiar, but you notice _lots_ of brackets, braces and parentheses.
+Despite the Bracketeer™ being powerful, it lacks flexibility.
+If the source code has any unbalanced brackets, braces or parentheses, the Bracketeer™ crashes and must be rebooted.
+To avoid such a scenario, you start writing code that can verify that brackets, braces, and parentheses are balanced before attempting to run it on the Bracketeer™.
diff --git a/exercises/practice/pascals-triangle/.docs/instructions.md b/exercises/practice/pascals-triangle/.docs/instructions.md
index f55678593..0f58f0069 100644
--- a/exercises/practice/pascals-triangle/.docs/instructions.md
+++ b/exercises/practice/pascals-triangle/.docs/instructions.md
@@ -1,8 +1,20 @@
 # Instructions
 
-Compute Pascal's triangle up to a given number of rows.
+Your task is to output the first N rows of Pascal's triangle.
 
-In Pascal's Triangle each number is computed by adding the numbers to the right and left of the current position in the previous row.
+[Pascal's triangle][wikipedia] is a triangular array of positive integers.
+
+In Pascal's triangle, the number of values in a row is equal to its row number (which starts at one).
+Therefore, the first row has one value, the second row has two values, and so on.
+
+The first (topmost) row has a single value: `1`.
+Subsequent rows' values are computed by adding the numbers directly to the right and left of the current position in the previous row.
+
+If the previous row does _not_ have a value to the left or right of the current position (which only happens for the leftmost and rightmost positions), treat that position's value as zero (effectively "ignoring" it in the summation).
+
+## Example
+
+Let's look at the first 5 rows of Pascal's Triangle:
 
 ```text
     1
@@ -10,5 +22,14 @@ In Pascal's Triangle each number is computed by adding the numbers to the right
   1 2 1
  1 3 3 1
 1 4 6 4 1
-# ... etc
 ```
+
+The topmost row has one value, which is `1`.
+
+The leftmost and rightmost values have only one preceding position to consider, which is the position to its right respectively to its left.
+With the topmost value being `1`, it follows from this that all the leftmost and rightmost values are also `1`.
+
+The other values all have two positions to consider.
+For example, the fifth row's (`1 4 6 4 1`) middle value is `6`, as the values to its left and right in the preceding row are `3` and `3`:
+
+[wikipedia]: https://en.wikipedia.org/wiki/Pascal%27s_triangle
diff --git a/exercises/practice/pascals-triangle/.docs/introduction.md b/exercises/practice/pascals-triangle/.docs/introduction.md
new file mode 100644
index 000000000..60b8ec30d
--- /dev/null
+++ b/exercises/practice/pascals-triangle/.docs/introduction.md
@@ -0,0 +1,22 @@
+# Introduction
+
+With the weather being great, you're not looking forward to spending an hour in a classroom.
+Annoyed, you enter the class room, where you notice a strangely satisfying triangle shape on the blackboard.
+Whilst waiting for your math teacher to arrive, you can't help but notice some patterns in the triangle: the outer values are all ones, each subsequent row has one more value than its previous row and the triangle is symmetrical.
+Weird!
+
+Not long after you sit down, your teacher enters the room and explains that this triangle is the famous [Pascal's triangle][wikipedia].
+
+Over the next hour, your teacher reveals some amazing things hidden in this triangle:
+
+- It can be used to compute how many ways you can pick K elements from N values.
+- It contains the Fibonacci sequence.
+- If you color odd and even numbers differently, you get a beautiful pattern called the [Sierpiński triangle][wikipedia-sierpinski-triangle].
+
+The teacher implores you and your classmates to lookup other uses, and assures you that there are lots more!
+At that moment, the school bell rings.
+You realize that for the past hour, you were completely absorbed in learning about Pascal's triangle.
+You quickly grab your laptop from your bag and go outside, ready to enjoy both the sunshine _and_ the wonders of Pascal's triangle.
+
+[wikipedia]: https://en.wikipedia.org/wiki/Pascal%27s_triangle
+[wikipedia-sierpinski-triangle]: https://en.wikipedia.org/wiki/Sierpi%C5%84ski_triangle
diff --git a/exercises/practice/perfect-numbers/.docs/instructions.md b/exercises/practice/perfect-numbers/.docs/instructions.md
index 0dae8867f..b2bc82ca3 100644
--- a/exercises/practice/perfect-numbers/.docs/instructions.md
+++ b/exercises/practice/perfect-numbers/.docs/instructions.md
@@ -1,24 +1,39 @@
 # Instructions
 
-Determine if a number is perfect, abundant, or deficient based on
-Nicomachus' (60 - 120 CE) classification scheme for positive integers.
-
-The Greek mathematician [Nicomachus][nicomachus] devised a classification scheme for positive integers, identifying each as belonging uniquely to the categories of **perfect**, **abundant**, or **deficient** based on their [aliquot sum][aliquot-sum].
-The aliquot sum is defined as the sum of the factors of a number not including the number itself.
-For example, the aliquot sum of 15 is (1 + 3 + 5) = 9
-
-- **Perfect**: aliquot sum = number
-  - 6 is a perfect number because (1 + 2 + 3) = 6
-  - 28 is a perfect number because (1 + 2 + 4 + 7 + 14) = 28
-- **Abundant**: aliquot sum > number
-  - 12 is an abundant number because (1 + 2 + 3 + 4 + 6) = 16
-  - 24 is an abundant number because (1 + 2 + 3 + 4 + 6 + 8 + 12) = 36
-- **Deficient**: aliquot sum < number
-  - 8 is a deficient number because (1 + 2 + 4) = 7
-  - Prime numbers are deficient
-
-Implement a way to determine whether a given number is **perfect**.
-Depending on your language track, you may also need to implement a way to determine whether a given number is **abundant** or **deficient**.
+Determine if a number is perfect, abundant, or deficient based on Nicomachus' (60 - 120 CE) classification scheme for positive integers.
+
+The Greek mathematician [Nicomachus][nicomachus] devised a classification scheme for positive integers, identifying each as belonging uniquely to the categories of [perfect](#perfect), [abundant](#abundant), or [deficient](#deficient) based on their [aliquot sum][aliquot-sum].
+The _aliquot sum_ is defined as the sum of the factors of a number not including the number itself.
+For example, the aliquot sum of `15` is `1 + 3 + 5 = 9`.
+
+## Perfect
+
+A number is perfect when it equals its aliquot sum.
+For example:
+
+- `6` is a perfect number because `1 + 2 + 3 = 6`
+- `28` is a perfect number because `1 + 2 + 4 + 7 + 14 = 28`
+
+## Abundant
+
+A number is abundant when it is less than its aliquot sum.
+For example:
+
+- `12` is an abundant number because `1 + 2 + 3 + 4 + 6 = 16`
+- `24` is an abundant number because `1 + 2 + 3 + 4 + 6 + 8 + 12 = 36`
+
+## Deficient
+
+A number is deficient when it is greater than its aliquot sum.
+For example:
+
+- `8` is a deficient number because `1 + 2 + 4 = 7`
+- Prime numbers are deficient
+
+## Task
+
+Implement a way to determine whether a given number is [perfect](#perfect).
+Depending on your language track, you may also need to implement a way to determine whether a given number is [abundant](#abundant) or [deficient](#deficient).
 
 [nicomachus]: https://en.wikipedia.org/wiki/Nicomachus
 [aliquot-sum]: https://en.wikipedia.org/wiki/Aliquot_sum
diff --git a/exercises/practice/phone-number/.docs/instructions.md b/exercises/practice/phone-number/.docs/instructions.md
index 6d3275cdf..62ba48e96 100644
--- a/exercises/practice/phone-number/.docs/instructions.md
+++ b/exercises/practice/phone-number/.docs/instructions.md
@@ -5,18 +5,20 @@ Clean up user-entered phone numbers so that they can be sent SMS messages.
 The **North American Numbering Plan (NANP)** is a telephone numbering system used by many countries in North America like the United States, Canada or Bermuda.
 All NANP-countries share the same international country code: `1`.
 
-NANP numbers are ten-digit numbers consisting of a three-digit Numbering Plan Area code, commonly known as *area code*, followed by a seven-digit local number.
-The first three digits of the local number represent the *exchange code*, followed by the unique four-digit number which is the *subscriber number*.
+NANP numbers are ten-digit numbers consisting of a three-digit Numbering Plan Area code, commonly known as _area code_, followed by a seven-digit local number.
+The first three digits of the local number represent the _exchange code_, followed by the unique four-digit number which is the _subscriber number_.
 
 The format is usually represented as
 
 ```text
-(NXX)-NXX-XXXX
+NXX NXX-XXXX
 ```
 
 where `N` is any digit from 2 through 9 and `X` is any digit from 0 through 9.
 
-Your task is to clean up differently formatted telephone numbers by removing punctuation and the country code (1) if present.
+Sometimes they also have the country code (represented as `1` or `+1`) prefixed.
+
+Your task is to clean up differently formatted telephone numbers by removing punctuation and the country code if present.
 
 For example, the inputs
 
diff --git a/exercises/practice/pig-latin/.docs/instructions.md b/exercises/practice/pig-latin/.docs/instructions.md
index 6c843080d..a9645ac23 100644
--- a/exercises/practice/pig-latin/.docs/instructions.md
+++ b/exercises/practice/pig-latin/.docs/instructions.md
@@ -19,7 +19,7 @@ For example:
 
 ## Rule 2
 
-If a word begins with a one or more consonants, first move those consonants to the end of the word and then add an `"ay"` sound to the end of the word.
+If a word begins with one or more consonants, first move those consonants to the end of the word and then add an `"ay"` sound to the end of the word.
 
 For example:
 
@@ -33,7 +33,7 @@ If a word starts with zero or more consonants followed by `"qu"`, first move tho
 
 For example:
 
-- `"quick"` -> `"ickqu"` -> `"ay"` (starts with `"qu"`, no preceding consonants)
+- `"quick"` -> `"ickqu"` -> `"ickquay"` (starts with `"qu"`, no preceding consonants)
 - `"square"` -> `"aresqu"` -> `"aresquay"` (starts with one consonant followed by `"qu`")
 
 ## Rule 4
diff --git a/exercises/practice/poker/.docs/instructions.md b/exercises/practice/poker/.docs/instructions.md
index 492fc4c9e..107cd49d6 100644
--- a/exercises/practice/poker/.docs/instructions.md
+++ b/exercises/practice/poker/.docs/instructions.md
@@ -2,6 +2,6 @@
 
 Pick the best hand(s) from a list of poker hands.
 
-See [wikipedia][poker-hands] for an overview of poker hands.
+See [Wikipedia][poker-hands] for an overview of poker hands.
 
 [poker-hands]: https://en.wikipedia.org/wiki/List_of_poker_hands
diff --git a/exercises/practice/poker/.meta/config.json b/exercises/practice/poker/.meta/config.json
index 33b79fbcd..f1c68db36 100644
--- a/exercises/practice/poker/.meta/config.json
+++ b/exercises/practice/poker/.meta/config.json
@@ -24,5 +24,5 @@
   },
   "blurb": "Pick the best hand(s) from a list of poker hands.",
   "source": "Inspired by the training course from Udacity.",
-  "source_url": "https://www.udacity.com/course/viewer#!/c-cs212/"
+  "source_url": "https://www.udacity.com/course/design-of-computer-programs--cs212"
 }
diff --git a/exercises/practice/protein-translation/.docs/instructions.md b/exercises/practice/protein-translation/.docs/instructions.md
index d9b9054cf..7dc34d2ed 100644
--- a/exercises/practice/protein-translation/.docs/instructions.md
+++ b/exercises/practice/protein-translation/.docs/instructions.md
@@ -29,16 +29,16 @@ Note the stop codon `"UAA"` terminates the translation and the final methionine
 
 Below are the codons and resulting Amino Acids needed for the exercise.
 
-Codon                 | Protein
-:---                  | :---
-AUG                   | Methionine
-UUU, UUC              | Phenylalanine
-UUA, UUG              | Leucine
-UCU, UCC, UCA, UCG    | Serine
-UAU, UAC              | Tyrosine
-UGU, UGC              | Cysteine
-UGG                   | Tryptophan
-UAA, UAG, UGA         | STOP
+| Codon              | Protein       |
+| :----------------- | :------------ |
+| AUG                | Methionine    |
+| UUU, UUC           | Phenylalanine |
+| UUA, UUG           | Leucine       |
+| UCU, UCC, UCA, UCG | Serine        |
+| UAU, UAC           | Tyrosine      |
+| UGU, UGC           | Cysteine      |
+| UGG                | Tryptophan    |
+| UAA, UAG, UGA      | STOP          |
 
 Learn more about [protein translation on Wikipedia][protein-translation].
 
diff --git a/exercises/practice/pythagorean-triplet/.meta/config.json b/exercises/practice/pythagorean-triplet/.meta/config.json
index 28c7f6cec..12e5ec945 100644
--- a/exercises/practice/pythagorean-triplet/.meta/config.json
+++ b/exercises/practice/pythagorean-triplet/.meta/config.json
@@ -24,7 +24,7 @@
       ".meta/Sources/PythagoreanTriplet/PythagoreanTripletExample.swift"
     ]
   },
-  "blurb": "There exists exactly one Pythagorean triplet for which a + b + c = 1000. Find the product a * b * c.",
+  "blurb": "There exists exactly one Pythagorean triplet for which a + b + c = 1000. Find the triplet.",
   "source": "Problem 9 at Project Euler",
   "source_url": "https://projecteuler.net/problem=9"
 }
diff --git a/exercises/practice/queen-attack/.docs/instructions.md b/exercises/practice/queen-attack/.docs/instructions.md
index ad7ea9547..97f22a0ae 100644
--- a/exercises/practice/queen-attack/.docs/instructions.md
+++ b/exercises/practice/queen-attack/.docs/instructions.md
@@ -8,18 +8,14 @@ A chessboard can be represented by an 8 by 8 array.
 
 So if you are told the white queen is at `c5` (zero-indexed at column 2, row 3) and the black queen at `f2` (zero-indexed at column 5, row 6), then you know that the set-up is like so:
 
-```text
-  a b c d e f g h
-8 _ _ _ _ _ _ _ _ 8
-7 _ _ _ _ _ _ _ _ 7
-6 _ _ _ _ _ _ _ _ 6
-5 _ _ W _ _ _ _ _ 5
-4 _ _ _ _ _ _ _ _ 4
-3 _ _ _ _ _ _ _ _ 3
-2 _ _ _ _ _ B _ _ 2
-1 _ _ _ _ _ _ _ _ 1
-  a b c d e f g h
-```
+![A chess board with two queens. Arrows emanating from the queen at c5 indicate possible directions of capture along file, rank and diagonal.](https://assets.exercism.org/images/exercises/queen-attack/queen-capture.svg)
 
 You are also able to answer whether the queens can attack each other.
 In this case, that answer would be yes, they can, because both pieces share a diagonal.
+
+## Credit
+
+The chessboard image was made by [habere-et-dispertire][habere-et-dispertire] using LaTeX and the [chessboard package][chessboard-package] by Ulrike Fischer.
+
+[habere-et-dispertire]: https://exercism.org/profiles/habere-et-dispertire
+[chessboard-package]: https://github.com/u-fischer/chessboard
diff --git a/exercises/practice/raindrops/.meta/config.json b/exercises/practice/raindrops/.meta/config.json
index 6564b857d..ef430fdff 100644
--- a/exercises/practice/raindrops/.meta/config.json
+++ b/exercises/practice/raindrops/.meta/config.json
@@ -22,7 +22,7 @@
       ".meta/Sources/Raindrops/RaindropsExample.swift"
     ]
   },
-  "blurb": "Convert a number to a string, the content of which depends on the number's factors.",
+  "blurb": "Convert a number into its corresponding raindrop sounds - Pling, Plang and Plong.",
   "source": "A variation on FizzBuzz, a famous technical interview question that is intended to weed out potential candidates. That question is itself derived from Fizz Buzz, a popular children's game for teaching division.",
   "source_url": "https://en.wikipedia.org/wiki/Fizz_buzz"
 }
diff --git a/exercises/practice/rotational-cipher/.docs/instructions.md b/exercises/practice/rotational-cipher/.docs/instructions.md
index 4dee51b35..4bf64ca1d 100644
--- a/exercises/practice/rotational-cipher/.docs/instructions.md
+++ b/exercises/practice/rotational-cipher/.docs/instructions.md
@@ -22,8 +22,8 @@ Ciphertext is written out in the same formatting as the input including spaces a
 
 ## Examples
 
-- ROT5  `omg` gives `trl`
-- ROT0  `c` gives `c`
+- ROT5 `omg` gives `trl`
+- ROT0 `c` gives `c`
 - ROT26 `Cool` gives `Cool`
 - ROT13 `The quick brown fox jumps over the lazy dog.` gives `Gur dhvpx oebja sbk whzcf bire gur ynml qbt.`
 - ROT13 `Gur dhvpx oebja sbk whzcf bire gur ynml qbt.` gives `The quick brown fox jumps over the lazy dog.`
diff --git a/exercises/practice/say/.docs/instructions.md b/exercises/practice/say/.docs/instructions.md
index fb4a6dfb9..ad3d34778 100644
--- a/exercises/practice/say/.docs/instructions.md
+++ b/exercises/practice/say/.docs/instructions.md
@@ -30,8 +30,6 @@ Implement breaking a number up into chunks of thousands.
 
 So `1234567890` should yield a list like 1, 234, 567, and 890, while the far simpler `1000` should yield just 1 and 0.
 
-The program must also report any values that are out of range.
-
 ## Step 3
 
 Now handle inserting the appropriate scale word between those chunks.
diff --git a/exercises/practice/scale-generator/.docs/instructions.md b/exercises/practice/scale-generator/.docs/instructions.md
index 23e06e1ab..ebb7debc7 100644
--- a/exercises/practice/scale-generator/.docs/instructions.md
+++ b/exercises/practice/scale-generator/.docs/instructions.md
@@ -56,13 +56,13 @@ Then, for each interval in the pattern, the next note is determined by starting
 
 For example, starting with G and using the seven intervals MMmMMMm, there would be the following eight notes:
 
-Note | Reason
---|--
-G | Tonic
-A | M indicates a whole step from G, skipping G♯
-B | M indicates a whole step from A, skipping A♯
-C | m indicates a half step from B, skipping nothing
-D | M indicates a whole step from C, skipping C♯
-E | M indicates a whole step from D, skipping D♯
-F♯ | M indicates a whole step from E, skipping F
-G | m indicates a half step from F♯, skipping nothing
+| Note | Reason                                            |
+| ---- | ------------------------------------------------- |
+| G    | Tonic                                             |
+| A    | M indicates a whole step from G, skipping G♯      |
+| B    | M indicates a whole step from A, skipping A♯      |
+| C    | m indicates a half step from B, skipping nothing  |
+| D    | M indicates a whole step from C, skipping C♯      |
+| E    | M indicates a whole step from D, skipping D♯      |
+| F♯   | M indicates a whole step from E, skipping F       |
+| G    | m indicates a half step from F♯, skipping nothing |
diff --git a/exercises/practice/series/.docs/instructions.md b/exercises/practice/series/.docs/instructions.md
index e32cc38c6..fd97a6706 100644
--- a/exercises/practice/series/.docs/instructions.md
+++ b/exercises/practice/series/.docs/instructions.md
@@ -15,5 +15,5 @@ And the following 4-digit series:
 
 And if you ask for a 6-digit series from a 5-digit string, you deserve whatever you get.
 
-Note that these series are only required to occupy *adjacent positions* in the input;
-the digits need not be *numerically consecutive*.
+Note that these series are only required to occupy _adjacent positions_ in the input;
+the digits need not be _numerically consecutive_.
diff --git a/exercises/practice/simple-cipher/.docs/instructions.md b/exercises/practice/simple-cipher/.docs/instructions.md
index 9167a1d33..475af6182 100644
--- a/exercises/practice/simple-cipher/.docs/instructions.md
+++ b/exercises/practice/simple-cipher/.docs/instructions.md
@@ -9,7 +9,7 @@ If anyone wishes to decipher these, and get at their meaning, he must substitute
 —Suetonius, Life of Julius Caesar
 
 Ciphers are very straight-forward algorithms that allow us to render text less readable while still allowing easy deciphering.
-They are vulnerable to many forms of cryptanalysis, but we are lucky that generally our little sisters are not cryptanalysts.
+They are vulnerable to many forms of cryptanalysis, but Caesar was lucky that his enemies were not cryptanalysts.
 
 The Caesar Cipher was used for some messages from Julius Caesar that were sent afield.
 Now Caesar knew that the cipher wasn't very good, but he had one ally in that respect: almost nobody could read well.
@@ -29,9 +29,9 @@ When "ldpdsdqgdehdu" is put into the decode function it would return the origina
 
 ## Step 2
 
-Shift ciphers are no fun though when your kid sister figures it out.
+Shift ciphers quickly cease to be useful when the opposition commander figures them out.
+So instead, let's try using a substitution cipher.
 Try amending the code to allow us to specify a key and use that for the shift distance.
-This is called a substitution cipher.
 
 Here's an example:
 
diff --git a/exercises/practice/space-age/.docs/instructions.md b/exercises/practice/space-age/.docs/instructions.md
index fe938cc09..f23b5e2c1 100644
--- a/exercises/practice/space-age/.docs/instructions.md
+++ b/exercises/practice/space-age/.docs/instructions.md
@@ -1,25 +1,28 @@
 # Instructions
 
-Given an age in seconds, calculate how old someone would be on:
+Given an age in seconds, calculate how old someone would be on a planet in our Solar System.
 
-- Mercury: orbital period 0.2408467 Earth years
-- Venus: orbital period 0.61519726 Earth years
-- Earth: orbital period 1.0 Earth years, 365.25 Earth days, or 31557600 seconds
-- Mars: orbital period 1.8808158 Earth years
-- Jupiter: orbital period 11.862615 Earth years
-- Saturn: orbital period 29.447498 Earth years
-- Uranus: orbital period 84.016846 Earth years
-- Neptune: orbital period 164.79132 Earth years
+One Earth year equals 365.25 Earth days, or 31,557,600 seconds.
+If you were told someone was 1,000,000,000 seconds old, their age would be 31.69 Earth-years.
 
-So if you were told someone were 1,000,000,000 seconds old, you should
-be able to say that they're 31.69 Earth-years old.
+For the other planets, you have to account for their orbital period in Earth Years:
 
-If you're wondering why Pluto didn't make the cut, go watch [this YouTube video][pluto-video].
+| Planet  | Orbital period in Earth Years |
+| ------- | ----------------------------- |
+| Mercury | 0.2408467                     |
+| Venus   | 0.61519726                    |
+| Earth   | 1.0                           |
+| Mars    | 1.8808158                     |
+| Jupiter | 11.862615                     |
+| Saturn  | 29.447498                     |
+| Uranus  | 84.016846                     |
+| Neptune | 164.79132                     |
 
-Note: The actual length of one complete orbit of the Earth around the sun is closer to 365.256 days (1 sidereal year).
+~~~~exercism/note
+The actual length of one complete orbit of the Earth around the sun is closer to 365.256 days (1 sidereal year).
 The Gregorian calendar has, on average, 365.2425 days.
 While not entirely accurate, 365.25 is the value used in this exercise.
 See [Year on Wikipedia][year] for more ways to measure a year.
 
-[pluto-video]: https://www.youtube.com/watch?v=Z_2gbGXzFbs
 [year]: https://en.wikipedia.org/wiki/Year#Summary
+~~~~
diff --git a/exercises/practice/space-age/.docs/introduction.md b/exercises/practice/space-age/.docs/introduction.md
new file mode 100644
index 000000000..014d78857
--- /dev/null
+++ b/exercises/practice/space-age/.docs/introduction.md
@@ -0,0 +1,20 @@
+# Introduction
+
+The year is 2525 and you've just embarked on a journey to visit all planets in the Solar System (Mercury, Venus, Earth, Mars, Jupiter, Saturn, Uranus and Neptune).
+The first stop is Mercury, where customs require you to fill out a form (bureaucracy is apparently _not_ Earth-specific).
+As you hand over the form to the customs officer, they scrutinize it and frown.
+"Do you _really_ expect me to believe you're just 50 years old?
+You must be closer to 200 years old!"
+
+Amused, you wait for the customs officer to start laughing, but they appear to be dead serious.
+You realize that you've entered your age in _Earth years_, but the officer expected it in _Mercury years_!
+As Mercury's orbital period around the sun is significantly shorter than Earth, you're actually a lot older in Mercury years.
+After some quick calculations, you're able to provide your age in Mercury Years.
+The customs officer smiles, satisfied, and waves you through.
+You make a mental note to pre-calculate your planet-specific age _before_ future customs checks, to avoid such mix-ups.
+
+~~~~exercism/note
+If you're wondering why Pluto didn't make the cut, go watch [this YouTube video][pluto-video].
+
+[pluto-video]: https://www.youtube.com/watch?v=Z_2gbGXzFbs
+~~~~
diff --git a/exercises/practice/strain/.meta/config.json b/exercises/practice/strain/.meta/config.json
index 970d7e60a..9901115fc 100644
--- a/exercises/practice/strain/.meta/config.json
+++ b/exercises/practice/strain/.meta/config.json
@@ -23,7 +23,7 @@
       ".meta/Sources/Strain/StrainExample.swift"
     ]
   },
-  "blurb": "Implement the `keep` and `discard` operation on collections. Given a collection and a predicate on the collection's elements, `keep` returns a new collection containing those elements where the predicate is true, while `discard` returns a new collection containing those elements where the predicate is false.",
+  "blurb": "Implement the `keep` and `discard` operation on collections.",
   "source": "Conversation with James Edward Gray II",
-  "source_url": "https://twitter.com/jeg2"
+  "source_url": "http://graysoftinc.com/"
 }
diff --git a/exercises/practice/transpose/.meta/config.json b/exercises/practice/transpose/.meta/config.json
index b1ebcc6e7..e8583330a 100644
--- a/exercises/practice/transpose/.meta/config.json
+++ b/exercises/practice/transpose/.meta/config.json
@@ -23,5 +23,5 @@
   },
   "blurb": "Take input text and output it transposed.",
   "source": "Reddit r/dailyprogrammer challenge #270 [Easy].",
-  "source_url": "https://www.reddit.com/r/dailyprogrammer/comments/4msu2x/challenge_270_easy_transpose_the_input_text"
+  "source_url": "https://web.archive.org/web/20230630051421/https://old.reddit.com/r/dailyprogrammer/comments/4msu2x/challenge_270_easy_transpose_the_input_text/"
 }
diff --git a/exercises/practice/wordy/.docs/instructions.md b/exercises/practice/wordy/.docs/instructions.md
index 0b9e67b6c..aafb9ee54 100644
--- a/exercises/practice/wordy/.docs/instructions.md
+++ b/exercises/practice/wordy/.docs/instructions.md
@@ -48,7 +48,7 @@ Since these are verbal word problems, evaluate the expression from left-to-right
 
 > What is 3 plus 2 multiplied by 3?
 
-15  (i.e. not 9)
+15 (i.e. not 9)
 
 ## Iteration 4 — Errors