Sync docs

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`.

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.

exercises/practice/bank-account/.docs/instructions.md

@@ -3,7 +3,7 @@
 Your task is to implement bank accounts supporting opening/closing, withdrawals, and deposits of money.
 
 As bank accounts can be accessed in many different ways (internet, mobile phones, automatic charges), your bank software must allow accounts to be safely accessed from multiple threads/processes (terminology depends on your programming language) in parallel.
-For example, there may be many deposits and withdrawals occurring in parallel; you need to ensure there is no [race conditions][wikipedia] between when you read the account balance and set the new balance.
+For example, there may be many deposits and withdrawals occurring in parallel; you need to ensure there are no [race conditions][wikipedia] between when you read the account balance and set the new balance.
 
 It should be possible to close an account; operations against a closed account must fail.
 

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
 

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.

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
+~~~~

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
+~~~~