From 98b50ff1904d23f6ff5db2fc2c668395c4476aa9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Andr=C3=A1s=20B=20Nagy?=
 <20251272+BNAndras@users.noreply.github.com>
Date: Thu, 5 Dec 2024 21:15:25 -0800
Subject: [PATCH] Sync docs and metadata

---
 .../practice/acronym/.docs/instructions.md    |  12 +-
 exercises/practice/acronym/.meta/config.json  |   2 +-
 .../practice/allergies/.docs/instructions.md  |   2 +-
 .../armstrong-numbers/.docs/instructions.md   |   4 +-
 .../atbash-cipher/.docs/instructions.md       |  19 ++-
 .../practice/atbash-cipher/.meta/config.json  |   2 +-
 .../binary-search/.docs/instructions.md       |  47 ++++----
 .../binary-search/.docs/introduction.md       |  13 +++
 .../practice/binary-search/.meta/config.json  |   4 +-
 .../practice/binary/.docs/instructions.md     |  13 +--
 .../circular-buffer/.docs/instructions.md     |  95 ++++++++-------
 .../circular-buffer/.meta/config.json         |   2 +-
 .../complex-numbers/.docs/instructions.md     | 109 +++++++++++++++---
 .../complex-numbers/.meta/config.json         |   2 +-
 .../practice/darts/.docs/instructions.md      |  12 +-
 exercises/practice/darts/.meta/config.json    |   2 +-
 .../practice/diamond/.docs/instructions.md    |  27 +++--
 exercises/practice/diamond/.meta/config.json  |   4 +-
 .../eliuds-eggs/.docs/instructions.md         |   2 +-
 .../eliuds-eggs/.docs/introduction.md         |  48 +++++---
 .../grade-school/.docs/instructions.md        |  46 +++-----
 .../practice/hamming/.docs/instructions.md    |  17 +--
 .../practice/hamming/.docs/introduction.md    |  12 ++
 exercises/practice/hamming/.meta/config.json  |   2 +-
 .../practice/hello-world/.meta/config.json    |   2 +-
 .../practice/isogram/.docs/instructions.md    |   2 +-
 .../practice/knapsack/.docs/instructions.md   |  34 ++----
 .../practice/knapsack/.docs/introduction.md   |  10 ++
 exercises/practice/luhn/.docs/instructions.md |   3 +-
 .../matching-brackets/.docs/instructions.md   |   8 +-
 .../matching-brackets/.docs/introduction.md   |   8 ++
 .../matching-brackets/.meta/config.json       |   5 +-
 .../pascals-triangle/.docs/instructions.md    |  30 ++++-
 .../pascals-triangle/.docs/introduction.md    |  22 ++++
 .../pascals-triangle/.meta/config.json        |   2 +-
 .../practice/pig-latin/.docs/instructions.md  |   4 +-
 .../protein-translation/.docs/instructions.md |  35 +++---
 .../queen-attack/.docs/instructions.md        |  20 ++--
 .../practice/raindrops/.meta/config.json      |   2 +-
 .../rna-transcription/.docs/instructions.md   |   6 +-
 .../rotational-cipher/.docs/instructions.md   |   4 +-
 .../secret-handshake/.docs/instructions.md    |  45 ++++++--
 .../secret-handshake/.docs/introduction.md    |   7 ++
 .../secret-handshake/.meta/config.json        |   4 +-
 .../practice/space-age/.docs/instructions.md  |  36 +++---
 .../practice/space-age/.docs/introduction.md  |  20 ++++
 .../square-root/.docs/instructions.md         |  17 ++-
 .../square-root/.docs/introduction.md         |  10 ++
 exercises/practice/yacht/.meta/config.json    |   2 +-
 49 files changed, 521 insertions(+), 315 deletions(-)
 create mode 100644 exercises/practice/binary-search/.docs/introduction.md
 create mode 100644 exercises/practice/hamming/.docs/introduction.md
 create mode 100644 exercises/practice/knapsack/.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/secret-handshake/.docs/introduction.md
 create mode 100644 exercises/practice/space-age/.docs/introduction.md
 create mode 100644 exercises/practice/square-root/.docs/introduction.md

diff --git a/exercises/practice/acronym/.docs/instructions.md b/exercises/practice/acronym/.docs/instructions.md
index 8943987a..133bd2cb 100644
--- a/exercises/practice/acronym/.docs/instructions.md
+++ b/exercises/practice/acronym/.docs/instructions.md
@@ -1,4 +1,4 @@
-# Description
+# Instructions
 
 Convert a phrase to its acronym.
 
@@ -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/acronym/.meta/config.json b/exercises/practice/acronym/.meta/config.json
index 553edbc1..e272a9a7 100644
--- a/exercises/practice/acronym/.meta/config.json
+++ b/exercises/practice/acronym/.meta/config.json
@@ -20,7 +20,7 @@
       "config.properties"
     ]
   },
-  "blurb": "Convert a phrase to its acronym.",
+  "blurb": "Convert a long phrase to its acronym.",
   "source": "Julien Vanier",
   "source_url": "https://github.com/monkbroc"
 }
diff --git a/exercises/practice/allergies/.docs/instructions.md b/exercises/practice/allergies/.docs/instructions.md
index a1394920..daf8cfde 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/armstrong-numbers/.docs/instructions.md b/exercises/practice/armstrong-numbers/.docs/instructions.md
index 744cfbe7..5e56bbe4 100644
--- a/exercises/practice/armstrong-numbers/.docs/instructions.md
+++ b/exercises/practice/armstrong-numbers/.docs/instructions.md
@@ -5,9 +5,9 @@ An [Armstrong number][armstrong-number] is a number that is the sum of its own d
 For example:
 
 - 9 is an Armstrong number, because `9 = 9^1 = 9`
-- 10 is *not* an Armstrong number, because `10 != 1^2 + 0^2 = 1`
+- 10 is _not_ an Armstrong number, because `10 != 1^2 + 0^2 = 1`
 - 153 is an Armstrong number, because: `153 = 1^3 + 5^3 + 3^3 = 1 + 125 + 27 = 153`
-- 154 is *not* an Armstrong number, because: `154 != 1^3 + 5^3 + 4^3 = 1 + 125 + 64 = 190`
+- 154 is _not_ an Armstrong number, because: `154 != 1^3 + 5^3 + 4^3 = 1 + 125 + 64 = 190`
 
 Write some code to determine whether a number is an Armstrong number.
 
diff --git a/exercises/practice/atbash-cipher/.docs/instructions.md b/exercises/practice/atbash-cipher/.docs/instructions.md
index 338f3b86..1e7627b1 100644
--- a/exercises/practice/atbash-cipher/.docs/instructions.md
+++ b/exercises/practice/atbash-cipher/.docs/instructions.md
@@ -1,11 +1,9 @@
-# Description
+# Instructions
 
-Create an implementation of the atbash cipher, an ancient encryption system created in the Middle East.
+Create an implementation of the Atbash cipher, an ancient encryption system created in the Middle East.
 
-The Atbash cipher is a simple substitution cipher that relies on
-transposing all the letters in the alphabet such that the resulting
-alphabet is backwards. The first letter is replaced with the last
-letter, the second with the second-last, and so on.
+The Atbash cipher is a simple substitution cipher that relies on transposing all the letters in the alphabet such that the resulting alphabet is backwards.
+The first letter is replaced with the last letter, the second with the second-last, and so on.
 
 An Atbash cipher for the Latin alphabet would be as follows:
 
@@ -14,13 +12,12 @@ Plain:  abcdefghijklmnopqrstuvwxyz
 Cipher: zyxwvutsrqponmlkjihgfedcba
 ```
 
-It is a very weak cipher because it only has one possible key, and it is
-a simple mono-alphabetic substitution cipher. However, this may not have
-been an issue in the cipher's time.
+It is a very weak cipher because it only has one possible key, and it is a simple mono-alphabetic substitution cipher.
+However, this may not have been an issue in the cipher's time.
 
-Ciphertext is written out in groups of fixed length, the traditional group size
-being 5 letters, leaving numbers unchanged, and punctuation is excluded.
+Ciphertext is written out in groups of fixed length, the traditional group size being 5 letters, leaving numbers unchanged, and punctuation is excluded.
 This is to make it harder to guess things based on word boundaries.
+All text will be encoded as lowercase letters.
 
 ## Examples
 
diff --git a/exercises/practice/atbash-cipher/.meta/config.json b/exercises/practice/atbash-cipher/.meta/config.json
index a4f0636b..67fed8fc 100644
--- a/exercises/practice/atbash-cipher/.meta/config.json
+++ b/exercises/practice/atbash-cipher/.meta/config.json
@@ -20,7 +20,7 @@
       "config.properties"
     ]
   },
-  "blurb": "Create an implementation of the atbash cipher, an ancient encryption system created in the Middle East.",
+  "blurb": "Create an implementation of the Atbash cipher, an ancient encryption system created in the Middle East.",
   "source": "Wikipedia",
   "source_url": "https://en.wikipedia.org/wiki/Atbash"
 }
diff --git a/exercises/practice/binary-search/.docs/instructions.md b/exercises/practice/binary-search/.docs/instructions.md
index ae45210e..12f4358e 100644
--- a/exercises/practice/binary-search/.docs/instructions.md
+++ b/exercises/practice/binary-search/.docs/instructions.md
@@ -1,36 +1,29 @@
 # Instructions
 
-Implement a binary search algorithm. Do not use any COBOL proprietary
-search routines (eg. SEARCH).
+Your task is to implement a binary search algorithm.
 
-Searching a sorted collection is a common task. A dictionary is a sorted
-list of word definitions. Given a word, one can find its definition. A
-telephone book is a sorted list of people's names, addresses, and
-telephone numbers. Knowing someone's name allows one to quickly find
-their telephone number and address.
+A binary search algorithm finds an item in a list by repeatedly splitting it in half, only keeping the half which contains the item we're looking for.
+It allows us to quickly narrow down the possible locations of our item until we find it, or until we've eliminated all possible locations.
 
-If the list to be searched contains more than a few items (a dozen, say)
-a binary search will require far fewer comparisons than a linear search,
-but it imposes the requirement that the list be sorted.
+~~~~exercism/caution
+Binary search only works when a list has been sorted.
+~~~~
 
-In computer science, a binary search or half-interval search algorithm
-finds the position of a specified input value (the search "key") within
-an array sorted by key value.
+The algorithm looks like this:
 
-In each step, the algorithm compares the search key value with the key
-value of the middle element of the array.
+- 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.
+- If every element of the list has been eliminated then the item is not in the list.
+- Otherwise, repeat the process on the part of the list that has not been eliminated.
 
-If the keys match, then a matching element has been found and its index,
-or position, is returned.
+Here's an example:
 
-Otherwise, if the search key is less than the middle element's key, then
-the algorithm repeats its action on the sub-array to the left of the
-middle element or, if the search key is greater, on the sub-array to the
-right.
+Let's say we're looking for the number 23 in the following sorted list: `[4, 8, 12, 16, 23, 28, 32]`.
 
-If the remaining array to be searched is empty, then the key cannot be
-found in the array and a special "not found" indication is returned.
-
-A binary search halves the number of items to check with each iteration,
-so locating an item (or determining its absence) takes logarithmic time.
-A binary search is a dichotomic divide and conquer search algorithm.
+- We start by comparing 23 with the middle element, 16.
+- Since 23 is greater than 16, we can eliminate the left half of the list, leaving us with `[23, 28, 32]`.
+- We then compare 23 with the new middle element, 28.
+- Since 23 is less than 28, we can eliminate the right half of the list: `[23]`.
+- We've found our item.
diff --git a/exercises/practice/binary-search/.docs/introduction.md b/exercises/practice/binary-search/.docs/introduction.md
new file mode 100644
index 00000000..03496599
--- /dev/null
+++ b/exercises/practice/binary-search/.docs/introduction.md
@@ -0,0 +1,13 @@
+# Introduction
+
+You have stumbled upon a group of mathematicians who are also singer-songwriters.
+They have written a song for each of their favorite numbers, and, as you can imagine, they have a lot of favorite numbers (like [0][zero] or [73][seventy-three] or [6174][kaprekars-constant]).
+
+You are curious to hear the song for your favorite number, but with so many songs to wade through, finding the right song could take a while.
+Fortunately, they have organized their songs in a playlist sorted by the title — which is simply the number that the song is about.
+
+You realize that you can use a binary search algorithm to quickly find a song given the title.
+
+[zero]: https://en.wikipedia.org/wiki/0
+[seventy-three]: https://en.wikipedia.org/wiki/73_(number)
+[kaprekars-constant]: https://en.wikipedia.org/wiki/6174_(number)
diff --git a/exercises/practice/binary-search/.meta/config.json b/exercises/practice/binary-search/.meta/config.json
index 11bbddab..c4ade28c 100644
--- a/exercises/practice/binary-search/.meta/config.json
+++ b/exercises/practice/binary-search/.meta/config.json
@@ -8,7 +8,7 @@
     ],
     "test": [
       "tst/binary-search/binary-search.cut"
-    ], 
+    ],
     "example": [
       ".meta/proof.ci.cob"
     ],
@@ -19,5 +19,5 @@
   },
   "blurb": "Implement a binary search algorithm.",
   "source": "Wikipedia",
-  "source_url": "http://en.wikipedia.org/wiki/Binary_search_algorithm"
+  "source_url": "https://en.wikipedia.org/wiki/Binary_search_algorithm"
 }
diff --git a/exercises/practice/binary/.docs/instructions.md b/exercises/practice/binary/.docs/instructions.md
index 946bb820..6722637e 100644
--- a/exercises/practice/binary/.docs/instructions.md
+++ b/exercises/practice/binary/.docs/instructions.md
@@ -1,10 +1,10 @@
-# Description
+# Instructions
 
 Convert a binary number, represented as a string (e.g. '101010'), to its decimal equivalent using first principles.
 
-Implement binary to decimal conversion. Given a binary input
-string, your program should produce a decimal output. The
-program should handle invalid inputs.
+Implement binary to decimal conversion.
+Given a binary input string, your program should produce a decimal output.
+The program should handle invalid inputs.
 
 ## Note
 
@@ -15,13 +15,12 @@ program should handle invalid inputs.
 
 Decimal is a base-10 system.
 
-A number 23 in base 10 notation can be understood
-as a linear combination of powers of 10:
+A number 23 in base 10 notation can be understood as a linear combination of powers of 10:
 
 - The rightmost digit gets multiplied by 10^0 = 1
 - The next number gets multiplied by 10^1 = 10
 - ...
-- The *n*th number gets multiplied by 10^*(n-1)*.
+- The nth number gets multiplied by 10^_(n-1)_.
 - All these values are summed.
 
 So: `23 => 2*10^1 + 3*10^0 => 2*10 + 3*1 = 23 base 10`
diff --git a/exercises/practice/circular-buffer/.docs/instructions.md b/exercises/practice/circular-buffer/.docs/instructions.md
index 7013fa47..2ba1fda2 100644
--- a/exercises/practice/circular-buffer/.docs/instructions.md
+++ b/exercises/practice/circular-buffer/.docs/instructions.md
@@ -1,51 +1,58 @@
-# Description
+# Instructions
 
-A circular buffer, cyclic buffer or ring buffer is a data structure that
-uses a single, fixed-size buffer as if it were connected end-to-end.
+A circular buffer, cyclic buffer or ring buffer is a data structure that uses a single, fixed-size buffer as if it were connected end-to-end.
 
-A circular buffer first starts empty and of some predefined length. For
-example, this is a 7-element buffer:
-<!-- prettier-ignore -->
-    [ ][ ][ ][ ][ ][ ][ ]
+A circular buffer first starts empty and of some predefined length.
+For example, this is a 7-element buffer:
 
-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
+[ ][ ][ ][ ][ ][ ][ ]
+```
 
-Then assume that two more elements are added — 2 & 3 — which get
-appended after the 1:
-<!-- prettier-ignore -->
-    [ ][ ][ ][1][2][3][ ]
+Assume that a 1 is written into the middle of the buffer (exact starting location does not matter in a circular buffer):
 
-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
+[ ][ ][ ][1][ ][ ][ ]
+```
+
+Then assume that two more elements are added — 2 & 3 — which get appended after the 1:
+
+```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:
+
+```text
+[ ][ ][ ][ ][ ][3][ ]
+```
 
 If the buffer has 7 elements then it is completely full:
-<!-- prettier-ignore -->
-    [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]
-
-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]
-
-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
+[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:
+
+```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:
+
+```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.
+
+```text
+[C][D][7][8][9][A][B]
+```
diff --git a/exercises/practice/circular-buffer/.meta/config.json b/exercises/practice/circular-buffer/.meta/config.json
index 3b657645..cdb66f30 100644
--- a/exercises/practice/circular-buffer/.meta/config.json
+++ b/exercises/practice/circular-buffer/.meta/config.json
@@ -20,7 +20,7 @@
       "config.properties"
     ]
   },
-  "blurb": "A circular buffer, cyclic buffer or ring buffer is a data structure that uses a single, fixed-size buffer as if it were connected end-to-end.",
+  "blurb": "A data structure that uses a single, fixed-size buffer as if it were connected end-to-end.",
   "source": "Wikipedia",
   "source_url": "https://en.wikipedia.org/wiki/Circular_buffer"
 }
diff --git a/exercises/practice/complex-numbers/.docs/instructions.md b/exercises/practice/complex-numbers/.docs/instructions.md
index c5a7a553..2b8a7a49 100644
--- a/exercises/practice/complex-numbers/.docs/instructions.md
+++ b/exercises/practice/complex-numbers/.docs/instructions.md
@@ -1,29 +1,100 @@
-# Description
+# Instructions
 
-A complex number is a number in the form `a + b * i` where `a` and `b` are real and `i` satisfies `i^2 = -1`.
+A **complex number** is expressed in the form `z = a + b * i`, where:
 
-`a` is called the real part and `b` is called the imaginary part of `z`.
-The conjugate of the number `a + b * i` is the number `a - b * i`.
-The absolute value of a complex number `z = a + b * i` is a real number `|z| = sqrt(a^2 + b^2)`. The square of the absolute value `|z|^2` is the result of multiplication of `z` by its complex conjugate.
+- `a` is the **real part** (a real number),
 
-The sum/difference of two complex numbers involves adding/subtracting their real and imaginary parts separately:
-`(a + i * b) + (c + i * d) = (a + c) + (b + d) * i`,
-`(a + i * b) - (c + i * d) = (a - c) + (b - d) * i`.
+- `b` is the **imaginary part** (also a real number), and
 
-Multiplication result is by definition
-`(a + i * b) * (c + i * d) = (a * c - b * d) + (b * c + a * d) * i`.
+- `i` is the **imaginary unit** satisfying `i^2 = -1`.
 
-The reciprocal of a non-zero complex number is
-`1 / (a + i * b) = a/(a^2 + b^2) - b/(a^2 + b^2) * i`.
+## Operations on Complex Numbers
 
-Dividing a complex number `a + i * b` by another `c + i * d` gives:
-`(a + i * b) / (c + i * d) = (a * c + b * d)/(c^2 + d^2) + (b * c - a * d)/(c^2 + d^2) * i`.
+### Conjugate
 
-Raising e to a complex exponent can be expressed as `e^(a + i * b) = e^a * e^(i * b)`, the last term of which is given by Euler's formula `e^(i * b) = cos(b) + i * sin(b)`.
+The conjugate of the complex number `z = a + b * i` is given by:
 
-Implement the following operations:
+```text
+zc = a - b * i
+```
 
-- addition, subtraction, multiplication and division of two complex numbers,
-- conjugate and absolute value of a given complex number.
+### Absolute Value
 
-Assume the programming language you are using does not have an implementation of complex numbers.
+The absolute value (or modulus) of `z` is defined as:
+
+```text
+|z| = sqrt(a^2 + b^2)
+```
+
+The square of the absolute value is computed as the product of `z` and its conjugate `zc`:
+
+```text
+|z|^2 = z * zc = a^2 + b^2
+```
+
+### Addition
+
+The sum of two complex numbers `z1 = a + b * i` and `z2 = c + d * i` is computed by adding their real and imaginary parts separately:
+
+```text
+z1 + z2 = (a + b * i) + (c + d * i)
+        = (a + c) + (b + d) * i
+```
+
+### Subtraction
+
+The difference of two complex numbers is obtained by subtracting their respective parts:
+
+```text
+z1 - z2 = (a + b * i) - (c + d * i)
+        = (a - c) + (b - d) * i
+```
+
+### Multiplication
+
+The product of two complex numbers is defined as:
+
+```text
+z1 * z2 = (a + b * i) * (c + d * i)
+        = (a * c - b * d) + (b * c + a * d) * i
+```
+
+### Reciprocal
+
+The reciprocal of a non-zero complex number is given by:
+
+```text
+1 / z = 1 / (a + b * i)
+      = a / (a^2 + b^2) - b / (a^2 + b^2) * i
+```
+
+### Division
+
+The division of one complex number by another is given by:
+
+```text
+z1 / z2 = z1 * (1 / z2)
+        = (a + b * i) / (c + d * i)
+        = (a * c + b * d) / (c^2 + d^2) + (b * c - a * d) / (c^2 + d^2) * i
+```
+
+### Exponentiation
+
+Raising _e_ (the base of the natural logarithm) to a complex exponent can be expressed using Euler's formula:
+
+```text
+e^(a + b * i) = e^a * e^(b * i)
+              = e^a * (cos(b) + i * sin(b))
+```
+
+## Implementation Requirements
+
+Given that you should not use built-in support for complex numbers, implement the following operations:
+
+- **addition** of two complex numbers
+- **subtraction** of two complex numbers
+- **multiplication** of two complex numbers
+- **division** of two complex numbers
+- **conjugate** of a complex number
+- **absolute value** of a complex number
+- **exponentiation** of _e_ (the base of the natural logarithm) to a complex number
diff --git a/exercises/practice/complex-numbers/.meta/config.json b/exercises/practice/complex-numbers/.meta/config.json
index 6b5d96dd..5924191e 100644
--- a/exercises/practice/complex-numbers/.meta/config.json
+++ b/exercises/practice/complex-numbers/.meta/config.json
@@ -20,7 +20,7 @@
       "config.properties"
     ]
   },
-  "blurb": "A complex number is a number in the form a + b * i where a and b are real and i satisfies i^2 = -1.",
+  "blurb": "Implement complex numbers.",
   "source": "Wikipedia",
   "source_url": "https://en.wikipedia.org/wiki/Complex_number"
 }
diff --git a/exercises/practice/darts/.docs/instructions.md b/exercises/practice/darts/.docs/instructions.md
index 70f0e53d..6518201c 100644
--- a/exercises/practice/darts/.docs/instructions.md
+++ b/exercises/practice/darts/.docs/instructions.md
@@ -1,11 +1,13 @@
 # Instructions
 
-Write a function that returns the earned points in a single toss of a Darts game.
+Calculate the points scored in a single toss of a Darts game.
 
 [Darts][darts] is a game where players throw darts at a [target][darts-target].
 
 In our particular instance of the game, the target rewards 4 different amounts of points, depending on where the dart lands:
 
+![Our dart scoreboard with values from a complete miss to a bullseye](https://assets.exercism.org/images/exercises/darts/darts-scoreboard.svg)
+
 - If the dart lands outside the target, player earns no points (0 points).
 - If the dart lands in the outer circle of the target, player earns 1 point.
 - If the dart lands in the middle circle of the target, player earns 5 points.
@@ -14,10 +16,16 @@ In our particular instance of the game, the target rewards 4 different amounts o
 The outer circle has a radius of 10 units (this is equivalent to the total radius for the entire target), the middle circle a radius of 5 units, and the inner circle a radius of 1.
 Of course, they are all centered at the same point — that is, the circles are [concentric][] defined by the coordinates (0, 0).
 
-Write a function that given a point in the target (defined by its [Cartesian coordinates][cartesian-coordinates] `x` and `y`, where `x` and `y` are [real][real-numbers]), returns the correct amount earned by a dart landing at that point.
+Given a point in the target (defined by its [Cartesian coordinates][cartesian-coordinates] `x` and `y`, where `x` and `y` are [real][real-numbers]), calculate the correct score earned by a dart landing at that point.
+
+## Credit
+
+The scoreboard image was created by [habere-et-dispertire][habere-et-dispertire] using [Inkscape][inkscape].
 
 [darts]: https://en.wikipedia.org/wiki/Darts
 [darts-target]: https://en.wikipedia.org/wiki/Darts#/media/File:Darts_in_a_dartboard.jpg
 [concentric]: https://mathworld.wolfram.com/ConcentricCircles.html
 [cartesian-coordinates]: https://www.mathsisfun.com/data/cartesian-coordinates.html
 [real-numbers]: https://www.mathsisfun.com/numbers/real-numbers.html
+[habere-et-dispertire]: https://exercism.org/profiles/habere-et-dispertire
+[inkscape]: https://en.wikipedia.org/wiki/Inkscape
diff --git a/exercises/practice/darts/.meta/config.json b/exercises/practice/darts/.meta/config.json
index 666284a2..9824d572 100644
--- a/exercises/practice/darts/.meta/config.json
+++ b/exercises/practice/darts/.meta/config.json
@@ -20,6 +20,6 @@
       "config.properties"
     ]
   },
-  "blurb": "Write a function that returns the earned points in a single toss of a Darts game.",
+  "blurb": "Calculate the points scored in a single toss of a Darts game.",
   "source": "Inspired by an exercise created by a professor Della Paolera in Argentina"
 }
diff --git a/exercises/practice/diamond/.docs/instructions.md b/exercises/practice/diamond/.docs/instructions.md
index 1de7016f..3034802f 100644
--- a/exercises/practice/diamond/.docs/instructions.md
+++ b/exercises/practice/diamond/.docs/instructions.md
@@ -1,22 +1,21 @@
 # Instructions
 
-The diamond kata takes as its input a letter, and outputs it in a diamond
-shape. Given a letter, it prints a diamond starting with 'A', with the
-supplied letter at the widest point.
+The diamond kata takes as its input a letter, and outputs it in a diamond shape.
+Given a letter, it prints a diamond starting with 'A', with the supplied letter at the widest point.
 
 ## Requirements
 
-* The first row contains one 'A'.
-* The last row contains one 'A'.
-* All rows, except the first and last, have exactly two identical letters.
-* All rows have as many trailing spaces as leading spaces. (This might be 0).
-* The diamond is horizontally symmetric.
-* The diamond is vertically symmetric.
-* The diamond has a square shape (width equals height).
-* The letters form a diamond shape.
-* The top half has the letters in ascending order.
-* The bottom half has the letters in descending order.
-* The four corners (containing the spaces) are triangles.
+- The first row contains one 'A'.
+- The last row contains one 'A'.
+- All rows, except the first and last, have exactly two identical letters.
+- All rows have as many trailing spaces as leading spaces. (This might be 0).
+- The diamond is horizontally symmetric.
+- The diamond is vertically symmetric.
+- The diamond has a square shape (width equals height).
+- The letters form a diamond shape.
+- The top half has the letters in ascending order.
+- The bottom half has the letters in descending order.
+- The four corners (containing the spaces) are triangles.
 
 ## Examples
 
diff --git a/exercises/practice/diamond/.meta/config.json b/exercises/practice/diamond/.meta/config.json
index 87d085b4..1e36f0f3 100644
--- a/exercises/practice/diamond/.meta/config.json
+++ b/exercises/practice/diamond/.meta/config.json
@@ -19,8 +19,8 @@
       "bin/fetch-cobolcheck.ps1",
       "config.properties"
     ]
-  }, 
+  },
   "blurb": "Given a letter, print a diamond starting with 'A' with the supplied letter at the widest point.",
   "source": "Seb Rose",
-  "source_url": "http://claysnow.co.uk/recycling-tests-in-tdd/"
+  "source_url": "https://web.archive.org/web/20220807163751/http://claysnow.co.uk/recycling-tests-in-tdd/"
 }
diff --git a/exercises/practice/eliuds-eggs/.docs/instructions.md b/exercises/practice/eliuds-eggs/.docs/instructions.md
index 061666c2..b0c2df59 100644
--- a/exercises/practice/eliuds-eggs/.docs/instructions.md
+++ b/exercises/practice/eliuds-eggs/.docs/instructions.md
@@ -5,4 +5,4 @@ Your task is to count the number of 1 bits in the binary representation of a num
 ## Restrictions
 
 Keep your hands off that bit-count functionality provided by your standard library!
-Solve this one yourself using other basic tools instead.
\ No newline at end of file
+Solve this one yourself using other basic tools instead.
diff --git a/exercises/practice/eliuds-eggs/.docs/introduction.md b/exercises/practice/eliuds-eggs/.docs/introduction.md
index 1e4f87c8..81989748 100644
--- a/exercises/practice/eliuds-eggs/.docs/introduction.md
+++ b/exercises/practice/eliuds-eggs/.docs/introduction.md
@@ -12,36 +12,54 @@ The position information encoding is calculated as follows:
 2. Convert the number from binary to decimal.
 3. Show the result on the display.
 
-Example 1:
+## Example 1
+
+![Seven individual nest boxes arranged in a row whose first, third, fourth and seventh nests each have a single egg.](https://assets.exercism.org/images/exercises/eliuds-eggs/example-1-coop.svg)
 
 ```text
-Chicken Coop:
  _ _ _ _ _ _ _
 |E| |E|E| | |E|
+```
+
+### Resulting Binary
 
-Resulting Binary:
- 1 0 1 1 0 0 1
+![1011001](https://assets.exercism.org/images/exercises/eliuds-eggs/example-1-binary.svg)
+
+```text
+ _ _ _ _ _ _ _
+|1|0|1|1|0|0|1|
+```
+
+### Decimal number on the display
 
-Decimal number on the display:
 89
 
-Actual eggs in the coop:
+### Actual eggs in the coop
+
 4
+
+## Example 2
+
+![Seven individual nest boxes arranged in a row where only the fourth nest has an egg.](https://assets.exercism.org/images/exercises/eliuds-eggs/example-2-coop.svg)
+
+```text
+ _ _ _ _ _ _ _
+| | | |E| | | |
 ```
 
-Example 2:
+### Resulting Binary
+
+![0001000](https://assets.exercism.org/images/exercises/eliuds-eggs/example-2-binary.svg)
 
 ```text
-Chicken Coop:
- _ _ _ _ _ _ _ _
-| | | |E| | | | |
+ _ _ _ _ _ _ _
+|0|0|0|1|0|0|0|
+```
 
-Resulting Binary:
- 0 0 0 1 0 0 0 0
+### Decimal number on the display
 
-Decimal number on the display:
 16
 
-Actual eggs in the coop:
+### Actual eggs in the coop
+
 1
-```
\ No newline at end of file
diff --git a/exercises/practice/grade-school/.docs/instructions.md b/exercises/practice/grade-school/.docs/instructions.md
index 012e7add..3cb1b5d5 100644
--- a/exercises/practice/grade-school/.docs/instructions.md
+++ b/exercises/practice/grade-school/.docs/instructions.md
@@ -1,41 +1,21 @@
 # Instructions
 
-Given students' names along with the grade that they are in, create a roster
-for the school.
+Given students' names along with the grade they are in, create a roster for the school.
 
 In the end, you should be able to:
 
-- Add a student's name to the roster for a grade
+- Add a student's name to the roster for a grade:
   - "Add Jim to grade 2."
   - "OK."
-- Get a list of all students enrolled in a grade
+- Get a list of all students enrolled in a grade:
   - "Which students are in grade 2?"
-  - "We've only got Jim just now."
-- Get a sorted list of all students in all grades.  Grades should sort
-  as 1, 2, 3, etc., and students within a grade should be sorted
-  alphabetically by name.
-  - "Who all is enrolled in school right now?"
-  - "Let me think. We have
-  Anna, Barb, and Charlie in grade 1,
-  Alex, Peter, and Zoe in grade 2
-  and Jim in grade 5.
-  So the answer is: Anna, Barb, Charlie, Alex, Peter, Zoe and Jim"
-
-Note that all our students only have one name  (It's a small town, what
-do you want?) and each student cannot be added more than once to a grade or the
-roster.
-In fact, when a test attempts to add the same student more than once, your
-implementation should indicate that this is incorrect.
-
-## For bonus points
-
-Did you get the tests passing and the code clean? If you want to, these
-are some additional things you could try:
-
-- If you're working in a language with mutable data structures and your
-  implementation allows outside code to mutate the school's internal DB
-  directly, see if you can prevent this. Feel free to introduce additional
-  tests.
-
-Then please share your thoughts in a comment on the submission. Did this
-experiment make the code better? Worse? Did you learn anything from it?
+  - "We've only got Jim right now."
+- Get a sorted list of all students in all grades.
+  Grades should be sorted as 1, 2, 3, etc., and students within a grade should be sorted alphabetically by name.
+  - "Who is enrolled in school right now?"
+  - "Let me think.
+    We have Anna, Barb, and Charlie in grade 1, Alex, Peter, and Zoe in grade 2, and Jim in grade 5.
+    So the answer is: Anna, Barb, Charlie, Alex, Peter, Zoe, and Jim."
+
+Note that all our students only have one name (it's a small town, what do you want?), and each student cannot be added more than once to a grade or the roster.
+If a test attempts to add the same student more than once, your implementation should indicate that this is incorrect.
diff --git a/exercises/practice/hamming/.docs/instructions.md b/exercises/practice/hamming/.docs/instructions.md
index 020fdd02..8f47a179 100644
--- a/exercises/practice/hamming/.docs/instructions.md
+++ b/exercises/practice/hamming/.docs/instructions.md
@@ -1,26 +1,15 @@
 # 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.
-In fact, the average human body experiences about 10 quadrillion cell divisions in a lifetime!
-
-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".
-
-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.
-
-The Hamming Distance is useful for lots of things in science, not just biology, so it's a nice phrase to be familiar with :)
+They have 7 differences, and therefore the Hamming distance is 7.
 
 ## Implementation notes
 
diff --git a/exercises/practice/hamming/.docs/introduction.md b/exercises/practice/hamming/.docs/introduction.md
new file mode 100644
index 00000000..8419bf47
--- /dev/null
+++ b/exercises/practice/hamming/.docs/introduction.md
@@ -0,0 +1,12 @@
+# Introduction
+
+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.
+In fact, the average human body experiences about 10 quadrillion cell divisions in a lifetime!
+
+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".
+
+The Hamming distance is useful in many areas of science, not just biology, so it's a nice phrase to be familiar with :)
diff --git a/exercises/practice/hamming/.meta/config.json b/exercises/practice/hamming/.meta/config.json
index 65d928cd..32d23dc4 100644
--- a/exercises/practice/hamming/.meta/config.json
+++ b/exercises/practice/hamming/.meta/config.json
@@ -20,7 +20,7 @@
       "config.properties"
     ]
   },
-  "blurb": "Calculate the Hamming difference between two DNA strands.",
+  "blurb": "Calculate the Hamming distance between two DNA strands.",
   "source": "The Calculating Point Mutations problem at Rosalind",
   "source_url": "https://rosalind.info/problems/hamm/"
 }
diff --git a/exercises/practice/hello-world/.meta/config.json b/exercises/practice/hello-world/.meta/config.json
index 303e69a1..41db1526 100644
--- a/exercises/practice/hello-world/.meta/config.json
+++ b/exercises/practice/hello-world/.meta/config.json
@@ -21,7 +21,7 @@
       "config.properties"
     ]
   },
-  "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 5e488447..2e8df851 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/knapsack/.docs/instructions.md b/exercises/practice/knapsack/.docs/instructions.md
index 812d1010..0ebf7914 100644
--- a/exercises/practice/knapsack/.docs/instructions.md
+++ b/exercises/practice/knapsack/.docs/instructions.md
@@ -1,25 +1,15 @@
 # Instructions
 
-In this exercise, let's try to solve a classic problem.
+Your task is to determine which items to take so that the total value of her selection is maximized, taking into account the knapsack's carrying capacity.
 
-Bob is a thief. After months of careful planning, he finally manages to
-crack the security systems of a high-class apartment.
-
-In front of him are many items, each with a value (v) and weight (w). Bob,
-of course, wants to maximize the total value he can get; he would gladly
-take all of the items if he could. However, to his horror, he realizes that
-the knapsack he carries with him can only hold so much weight (W).
-
-Given a knapsack with a specific carrying capacity (W), help Bob determine
-the maximum value he can get from the items in the house. Note that Bob can
-take only one of each item.
-
-All values given will be strictly positive. Items will be represented as a
-list of pairs, `wi` and `vi`, where the first element `wi` is the weight of
-the *i*th item and `vi` is the value for that item.
+Items will be represented as a list of items.
+Each item will have a weight and value.
+All values given will be strictly positive.
+Lhakpa can take only one of each item.
 
 For example:
 
+```text
 Items: [
   { "weight": 5, "value": 10 },
   { "weight": 4, "value": 40 },
@@ -27,11 +17,9 @@ Items: [
   { "weight": 4, "value": 50 }
 ]
 
-Knapsack Limit: 10
-
-For the above, the first item has weight 5 and value 10, the second item has
-weight 4 and value 40, and so on.
+Knapsack Maximum Weight: 10
+```
 
-In this example, Bob should take the second and fourth item to maximize his
-value, which, in this case, is 90. He cannot get more than 90 as his
-knapsack has a weight limit of 10.
+For the above, the first item has weight 5 and value 10, the second item has weight 4 and value 40, and so on.
+In this example, Lhakpa should take the second and fourth item to maximize her value, which, in this case, is 90.
+She cannot get more than 90 as her knapsack has a weight limit of 10.
diff --git a/exercises/practice/knapsack/.docs/introduction.md b/exercises/practice/knapsack/.docs/introduction.md
new file mode 100644
index 00000000..9ac9df59
--- /dev/null
+++ b/exercises/practice/knapsack/.docs/introduction.md
@@ -0,0 +1,10 @@
+# Introduction
+
+Lhakpa is a [Sherpa][sherpa] mountain guide and porter.
+After months of careful planning, the expedition Lhakpa works for is about to leave.
+She will be paid the value she carried to the base camp.
+
+In front of her are many items, each with a value and weight.
+Lhakpa would gladly take all of the items, but her knapsack can only hold so much weight.
+
+[sherpa]: https://en.wikipedia.org/wiki/Sherpa_people#Mountaineering
diff --git a/exercises/practice/luhn/.docs/instructions.md b/exercises/practice/luhn/.docs/instructions.md
index 8cbe791f..49934c10 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 707e9921..ea170842 100644
--- a/exercises/practice/matching-brackets/.docs/instructions.md
+++ b/exercises/practice/matching-brackets/.docs/instructions.md
@@ -1,5 +1,5 @@
-# Description
+# Instructions
 
-Given a string containing brackets `[]`, braces `{}`, parentheses `()`,
-or any combination thereof, verify that any and all pairs are matched
-and nested correctly.
+Given a string containing brackets `[]`, braces `{}`, parentheses `()`, or any combination thereof, verify that any and all pairs are matched and nested correctly.
+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 00000000..0618221b
--- /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/matching-brackets/.meta/config.json b/exercises/practice/matching-brackets/.meta/config.json
index 9e8ed414..252b0f16 100644
--- a/exercises/practice/matching-brackets/.meta/config.json
+++ b/exercises/practice/matching-brackets/.meta/config.json
@@ -20,7 +20,6 @@
       "config.properties"
     ]
   },
-  "blurb": "Bob is a lackadaisical teenager. In conversation, his responses are very limited.",
-  "source": "Inspired by the 'Deaf Grandma' exercise in Chris Pine's Learn to Program tutorial.",
-  "source_url": "http://pine.fm/LearnToProgram/?Chapter=06"
+  "blurb": "Make sure the brackets and braces all match.",
+  "source": "Ginna Baker"
 }
diff --git a/exercises/practice/pascals-triangle/.docs/instructions.md b/exercises/practice/pascals-triangle/.docs/instructions.md
index 58d127b2..0f58f006 100644
--- a/exercises/practice/pascals-triangle/.docs/instructions.md
+++ b/exercises/practice/pascals-triangle/.docs/instructions.md
@@ -1,9 +1,20 @@
-# Description
+# 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
@@ -11,5 +22,14 @@ the right and left of the current position in the previous row.
   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 00000000..60b8ec30
--- /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/pascals-triangle/.meta/config.json b/exercises/practice/pascals-triangle/.meta/config.json
index 4bbe7736..37885395 100644
--- a/exercises/practice/pascals-triangle/.meta/config.json
+++ b/exercises/practice/pascals-triangle/.meta/config.json
@@ -22,5 +22,5 @@
   },
   "blurb": "Compute Pascal's triangle up to a given number of rows.",
   "source": "Pascal's Triangle at Wolfram Math World",
-  "source_url": "http://mathworld.wolfram.com/PascalsTriangle.html"
+  "source_url": "https://www.wolframalpha.com/input/?i=Pascal%27s+triangle"
 }
diff --git a/exercises/practice/pig-latin/.docs/instructions.md b/exercises/practice/pig-latin/.docs/instructions.md
index 6c843080..a9645ac2 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/protein-translation/.docs/instructions.md b/exercises/practice/protein-translation/.docs/instructions.md
index 826a61cf..44880802 100644
--- a/exercises/practice/protein-translation/.docs/instructions.md
+++ b/exercises/practice/protein-translation/.docs/instructions.md
@@ -2,16 +2,17 @@
 
 Translate RNA sequences into proteins.
 
-RNA can be broken into three nucleotide sequences called codons, and then translated to a polypeptide like so:
+RNA can be broken into three-nucleotide sequences called codons, and then translated to a protein like so:
 
 RNA: `"AUGUUUUCU"` => translates to
 
 Codons: `"AUG", "UUU", "UCU"`
-=> which become a polypeptide with the following sequence =>
+=> which become a protein with the following sequence =>
 
 Protein: `"Methionine", "Phenylalanine", "Serine"`
- 
-There are 64 codons which in turn correspond to 20 amino acids; however, all of the codon sequences and resulting amino acids are not important in this exercise.  If it works for one codon, the program should work for all of them.
+
+There are 64 codons which in turn correspond to 20 amino acids; however, all of the codon sequences and resulting amino acids are not important in this exercise.
+If it works for one codon, the program should work for all of them.
 However, feel free to expand the list in the test suite to include them all.
 
 There are also three terminating codons (also known as 'STOP' codons); if any of these codons are encountered (by the ribosome), all translation ends and the protein is terminated.
@@ -26,17 +27,19 @@ Protein: `"Methionine", "Phenylalanine", "Serine"`
 
 Note the stop codon `"UAA"` terminates the translation and the final methionine is not translated into the protein sequence.
 
-Below are the codons and resulting Amino Acids needed for the exercise.
+Below are the codons and resulting amino acids needed for the exercise.
+
+| Codon              | Amino Acid    |
+| :----------------- | :------------ |
+| 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].
 
-Learn more about [protein translation on Wikipedia](http://en.wikipedia.org/wiki/Translation_(biology))
+[protein-translation]: https://en.wikipedia.org/wiki/Translation_(biology)
diff --git a/exercises/practice/queen-attack/.docs/instructions.md b/exercises/practice/queen-attack/.docs/instructions.md
index ad7ea954..97f22a0a 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 9d179264..a539dd56 100644
--- a/exercises/practice/raindrops/.meta/config.json
+++ b/exercises/practice/raindrops/.meta/config.json
@@ -20,7 +20,7 @@
       "config.properties"
     ]
   },
-  "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/rna-transcription/.docs/instructions.md b/exercises/practice/rna-transcription/.docs/instructions.md
index 36da381f..4dbfd3a2 100644
--- a/exercises/practice/rna-transcription/.docs/instructions.md
+++ b/exercises/practice/rna-transcription/.docs/instructions.md
@@ -1,12 +1,12 @@
 # Instructions
 
-Your task is determine the RNA complement of a given DNA sequence.
+Your task is to determine the RNA complement of a given DNA sequence.
 
 Both DNA and RNA strands are a sequence of nucleotides.
 
-The four nucleotides found in DNA are adenine (**A**), cytosine (**C**), guanine (**G**) and thymine (**T**).
+The four nucleotides found in DNA are adenine (**A**), cytosine (**C**), guanine (**G**), and thymine (**T**).
 
-The four nucleotides found in RNA are adenine (**A**), cytosine (**C**), guanine (**G**) and uracil (**U**).
+The four nucleotides found in RNA are adenine (**A**), cytosine (**C**), guanine (**G**), and uracil (**U**).
 
 Given a DNA strand, its transcribed RNA strand is formed by replacing each nucleotide with its complement:
 
diff --git a/exercises/practice/rotational-cipher/.docs/instructions.md b/exercises/practice/rotational-cipher/.docs/instructions.md
index 4dee51b3..4bf64ca1 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/secret-handshake/.docs/instructions.md b/exercises/practice/secret-handshake/.docs/instructions.md
index d4d57b80..d2120b9b 100644
--- a/exercises/practice/secret-handshake/.docs/instructions.md
+++ b/exercises/practice/secret-handshake/.docs/instructions.md
@@ -1,27 +1,48 @@
 # Instructions
 
-> There are 10 types of people in the world: Those who understand
-> binary, and those who don't.
+Your task is to convert a number between 1 and 31 to a sequence of actions in the secret handshake.
 
-You and your fellow cohort of those in the "know" when it comes to
-binary decide to come up with a secret "handshake".
+The sequence of actions is chosen by looking at the rightmost five digits of the number once it's been converted to binary.
+Start at the right-most digit and move left.
 
-```text
+The actions for each number place are:
+
+```plaintext
 00001 = wink
 00010 = double blink
 00100 = close your eyes
 01000 = jump
+10000 = Reverse the order of the operations in the secret handshake.
+```
 
+Let's use the number `9` as an example:
 
-10000 = Reverse the order of the operations in the secret handshake.
+- 9 in binary is `1001`.
+- The digit that is farthest to the right is 1, so the first action is `wink`.
+- Going left, the next digit is 0, so there is no double-blink.
+- Going left again, the next digit is 0, so you leave your eyes open.
+- Going left again, the next digit is 1, so you jump.
+
+That was the last digit, so the final code is:
+
+```plaintext
+wink, jump
 ```
 
-Given a decimal number, convert it to the appropriate sequence of events for a secret handshake.
+Given the number 26, which is `11010` in binary, we get the following actions:
+
+- double blink
+- jump
+- reverse actions
 
-Here's a couple of examples:
+The secret handshake for 26 is therefore:
+
+```plaintext
+jump, double blink
+```
 
-Given the decimal input 3, the function would return the array
-["wink", "double blink"] because the decimal number 3 is 2+1 in powers of two and thus `11` in binary.
+~~~~exercism/note
+If you aren't sure what binary is or how it works, check out [this binary tutorial][intro-to-binary].
 
-Let's now examine the input 19 which is 16+2+1 in powers of two and thus `10011` in binary.
-Recalling that the addition of 16 (`10000` in binary) reverses an array and that we already know what array is returned given input 3, the array returned for input 19 is ["double blink", "wink"].
+[intro-to-binary]: https://medium.com/basecs/bits-bytes-building-with-binary-13cb4289aafa
+~~~~
diff --git a/exercises/practice/secret-handshake/.docs/introduction.md b/exercises/practice/secret-handshake/.docs/introduction.md
new file mode 100644
index 00000000..176b92e8
--- /dev/null
+++ b/exercises/practice/secret-handshake/.docs/introduction.md
@@ -0,0 +1,7 @@
+# Introduction
+
+You are starting a secret coding club with some friends and friends-of-friends.
+Not everyone knows each other, so you and your friends have decided to create a secret handshake that you can use to recognize that someone is a member.
+You don't want anyone who isn't in the know to be able to crack the code.
+
+You've designed the code so that one person says a number between 1 and 31, and the other person turns it into a series of actions.
diff --git a/exercises/practice/secret-handshake/.meta/config.json b/exercises/practice/secret-handshake/.meta/config.json
index ddc680b8..b6ccd237 100644
--- a/exercises/practice/secret-handshake/.meta/config.json
+++ b/exercises/practice/secret-handshake/.meta/config.json
@@ -10,7 +10,7 @@
       "tst/secret-handshake/secret-handshake.cut"
     ],
     "example": [
-      ".meta/proof.ci.cob" 
+      ".meta/proof.ci.cob"
     ],
     "invalidator": [
       "test.sh",
@@ -19,5 +19,5 @@
   },
   "blurb": "Given a decimal number, convert it to the appropriate sequence of events for a secret handshake.",
   "source": "Bert, in Mary Poppins",
-  "source_url": "http://www.imdb.com/title/tt0058331/quotes/qt0437047"
+  "source_url": "https://www.imdb.com/title/tt0058331/quotes/?item=qt0437047"
 }
diff --git a/exercises/practice/space-age/.docs/instructions.md b/exercises/practice/space-age/.docs/instructions.md
index 9e48f0ec..f23b5e2c 100644
--- a/exercises/practice/space-age/.docs/instructions.md
+++ b/exercises/practice/space-age/.docs/instructions.md
@@ -1,18 +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](http://www.youtube.com/watch?v=Z_2gbGXzFbs).
+| 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                     |
+
+~~~~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.
+
+[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 00000000..014d7885
--- /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/square-root/.docs/instructions.md b/exercises/practice/square-root/.docs/instructions.md
index e9905e9d..d258b868 100644
--- a/exercises/practice/square-root/.docs/instructions.md
+++ b/exercises/practice/square-root/.docs/instructions.md
@@ -1,13 +1,18 @@
 # Instructions
 
-Given a natural radicand, return its square root.
+Your task is to calculate the square root of a given number.
 
-Note that the term "radicand" refers to the number for which the root is to be determined.
-That is, it is the number under the root symbol.
+- Try to avoid using the pre-existing math libraries of your language.
+- As input you'll be given a positive whole number, i.e. 1, 2, 3, 4…
+- You are only required to handle cases where the result is a positive whole number.
 
-Check out the Wikipedia pages on [square root][square-root] and [methods of computing square roots][computing-square-roots].
+Some potential approaches:
 
-Recall also that natural numbers are positive real whole numbers (i.e. 1, 2, 3 and up).
+- Linear or binary search for a number that gives the input number when squared.
+- Successive approximation using Newton's or Heron's method.
+- Calculating one digit at a time or one bit at a time.
 
-[square-root]: https://en.wikipedia.org/wiki/Square_root
+You can check out the Wikipedia pages on [integer square root][integer-square-root] and [methods of computing square roots][computing-square-roots] to help with choosing a method of calculation.
+
+[integer-square-root]: https://en.wikipedia.org/wiki/Integer_square_root
 [computing-square-roots]: https://en.wikipedia.org/wiki/Methods_of_computing_square_roots
diff --git a/exercises/practice/square-root/.docs/introduction.md b/exercises/practice/square-root/.docs/introduction.md
new file mode 100644
index 00000000..1d692934
--- /dev/null
+++ b/exercises/practice/square-root/.docs/introduction.md
@@ -0,0 +1,10 @@
+# Introduction
+
+We are launching a deep space exploration rocket and we need a way to make sure the navigation system stays on target.
+
+As the first step in our calculation, we take a target number and find its square root (that is, the number that when multiplied by itself equals the target number).
+
+The journey will be very long.
+To make the batteries last as long as possible, we had to make our rocket's onboard computer very power efficient.
+Unfortunately that means that we can't rely on fancy math libraries and functions, as they use more power.
+Instead we want to implement our own square root calculation.
diff --git a/exercises/practice/yacht/.meta/config.json b/exercises/practice/yacht/.meta/config.json
index ee7545ee..9c6ccd53 100644
--- a/exercises/practice/yacht/.meta/config.json
+++ b/exercises/practice/yacht/.meta/config.json
@@ -21,6 +21,6 @@
     ]
   },
   "blurb": "Score a single throw of dice in the game Yacht.",
-  "source": "James Kilfiger, using wikipedia",
+  "source": "James Kilfiger, using Wikipedia",
   "source_url": "https://en.wikipedia.org/wiki/Yacht_(dice_game)"
 }