More docs and metadata

exercises/practice/all-your-base/.docs/instructions.md

@@ -1,9 +1,6 @@
 # Instructions
 
-Convert a number, represented as a sequence of digits in one base, to any other base.
-
-Implement general base conversion.
-Given a number in base **a**, represented as a sequence of digits, convert it to base **b**.
+Convert a sequence of digits in one base, representing a number, into a sequence of digits in another base, representing the same number.
 
 ~~~~exercism/note
 Try to implement the conversion yourself.
@@ -14,22 +11,17 @@ Do not use something else to perform the conversion for you.
 
 In positional notation, a number in base **b** can be understood as a linear combination of powers of **b**.
 
-The number 42, _in base 10_, means:
 The number 42, _in base 10_, means:
 
-`(4 * 10^1) + (2 * 10^0)`
+`(4 × 10¹) + (2 × 10⁰)`
 
-The number 101010, _in base 2_, means:
 The number 101010, _in base 2_, means:
 
-`(1 * 2^5) + (0 * 2^4) + (1 * 2^3) + (0 * 2^2) + (1 * 2^1) + (0 * 2^0)`
+`(1 × 2⁵) + (0 × 2⁴) + (1 × 2³) + (0 × 2²) + (1 × 2¹) + (0 × 2⁰)`
 
 The number 1120, _in base 3_, means:
-The number 1120, _in base 3_, means:
-
-`(1 * 3^3) + (1 * 3^2) + (2 * 3^1) + (0 * 3^0)`
 
-_Yes. Those three numbers above are exactly the same. Congratulations!_
+`(1 × 3³) + (1 × 3²) + (2 × 3¹) + (0 × 3⁰)`
 
 _Yes. Those three numbers above are exactly the same. Congratulations!_
 

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/leap/.docs/instructions.md

@@ -1,22 +1,3 @@
 # Instructions
 
-Given a year, report if it is a leap year.
-
-The tricky thing here is that a leap year in the Gregorian calendar occurs:
-
-```text
-on every year that is evenly divisible by 4
-  except every year that is evenly divisible by 100
-    unless the year is also evenly divisible by 400
-```
-
-For example, 1997 is not a leap year, but 1996 is.
-1900 is not a leap year, but 2000 is.
-
-## Notes
-
-Though our exercise adopts some very simple rules, there is more to learn!
-
-For a delightful, four minute explanation of the whole leap year phenomenon, go watch [this youtube video][video].
-
-[video]: https://www.youtube.com/watch?v=xX96xng7sAE
+Your task is to determine whether a given year is a leap year.

exercises/practice/minesweeper/.docs/instructions.md

@@ -1,19 +1,13 @@
 # Instructions
 
-Add the mine counts to a completed Minesweeper board.
+Your task is to add the mine counts to empty squares in a completed Minesweeper board.
+The board itself is a rectangle composed of squares that are either empty (`' '`) or a mine (`'*'`).
 
-Minesweeper is a popular game where the user has to find the mines using numeric hints that indicate how many mines are directly adjacent (horizontally, vertically, diagonally) to a square.
+For each empty square, count the number of mines adjacent to it (horizontally, vertically, diagonally).
+If the empty square has no adjacent mines, leave it empty.
+Otherwise replace it with the adjacent mines count.
 
-In this exercise you have to create some code that counts the number of mines adjacent to a given empty square and replaces that square with the count.
-
-The board is a rectangle composed of blank space (' ') characters.
-A mine is represented by an asterisk (`*`) character.
-
-If a given space has no adjacent mines at all, leave that square blank.
-
-## Examples
-
-For example you may receive a 5 x 4 board like this (empty spaces are represented here with the '·' character for display on screen):
+For example, you may receive a 5 x 4 board like this (empty spaces are represented here with the '·' character for display on screen):
 
 ```text
 ·*·*·

exercises/practice/raindrops/.docs/instructions.md

@@ -1,8 +1,6 @@
 # Instructions
 
-Your task is to convert a number into a string that contains raindrop sounds corresponding to certain potential factors.
-A factor is a number that evenly divides into another number, leaving no remainder.
-The simplest way to test if one number is a factor of another is to use the [modulo operation][modulo].
+Your task is to convert a number into its corresponding raindrop sounds.
 
 If a given number:
 
@@ -13,8 +11,14 @@ If a given number:
 
 ## Examples
 
-- 28 has 7 as a factor, but not 3 or 5, so the result would be "Plong".
-- 30 has both 3 and 5 as factors, but not 7, so the result would be "PlingPlang".
-- 34 is not factored by 3, 5, or 7, so the result would be "34".
+- 28 is divisible by 7, but not 3 or 5, so the result would be `"Plong"`.
+- 30 is divisible by 3 and 5, but not 7, so the result would be `"PlingPlang"`.
+- 34 is not divisible by 3, 5, or 7, so the result would be `"34"`.
 
+~~~~exercism/note
+A common way to test if one number is evenly divisible by another is to compare the [remainder][remainder] or [modulus][modulo] to zero.
+Most languages provide operators or functions for one (or both) of these.
+
+[remainder]: https://exercism.org/docs/programming/operators/remainder
 [modulo]: https://en.wikipedia.org/wiki/Modulo_operation
+~~~~

exercises/practice/raindrops/.meta/config.json

@@ -1,5 +1,5 @@
 {
-  "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.",
   "authors": [
     "gabrielperales"
   ],

exercises/practice/roman-numerals/.docs/instructions.md

@@ -1,41 +1,12 @@
-# Instructions
+# Introduction
 
-Write a function to convert from normal numbers to Roman Numerals.
+Your task is to convert a number from Arabic numerals to Roman numerals.
 
-The Romans were a clever bunch.
-They conquered most of Europe and ruled it for hundreds of years.
-They invented concrete and straight roads and even bikinis.
-One thing they never discovered though was the number zero.
-This made writing and dating extensive histories of their exploits slightly more challenging, but the system of numbers they came up with is still in use today.
-For example the BBC uses Roman numerals to date their programs.
+For this exercise, we are only concerned about traditional Roman numerals, in which the largest number is MMMCMXCIX (or 3,999).
 
-The Romans wrote numbers using letters - I, V, X, L, C, D, M.
-(notice these letters have lots of straight lines and are hence easy to hack into stone tablets).
+~~~~exercism/note
+There are lots of different ways to convert between Arabic and Roman numerals.
+We recommend taking a naive approach first to familiarise yourself with the concept of Roman numerals and then search for more efficient methods.
 
-```text
- 1  => I
-10  => X
- 7  => VII
-```
-
-The maximum number supported by this notation is 3,999.
-(The Romans themselves didn't tend to go any higher)
-
-Wikipedia says: Modern Roman numerals ... are written by expressing each digit separately starting with the left most digit and skipping any digit with a value of zero.
-
-To see this in practice, consider the example of 1990.
-
-In Roman numerals 1990 is MCMXC:
-
-1000=M
-900=CM
-90=XC
-
-2008 is written as MMVIII:
-
-2000=MM
-8=VIII
-
-Learn more about [Roman numerals on Wikipedia][roman-numerals].
-
-[roman-numerals]: https://wiki.imperivm-romanvm.com/wiki/Roman_Numerals
+Make sure to check out our Deep Dive video at the end to explore the different approaches you can take!
+~~~~

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