Sync docs and metadata (#195)

Author: BNAndras

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

@@ -1,20 +1,24 @@
 # 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.
 
-The rules of `raindrops` are that if a given number:
+If a given number:
 
-- has 3 as a factor, add 'Pling' to the result.
-- has 5 as a factor, add 'Plang' to the result.
-- has 7 as a factor, add 'Plong' to the result.
-- _does not_ have any of 3, 5, or 7 as a factor, the result should be the digits of the number.
+- is divisible by 3, add "Pling" to the result.
+- is divisible by 5, add "Plang" to the result.
+- is divisible by 7, add "Plong" to the result.
+- **is not** divisible by 3, 5, or 7, the result should be the number as a string.
 
 ## 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/.docs/introduction.md

@@ -0,0 +1,3 @@
+# Introduction
+
+Raindrops is a slightly more complex version of the FizzBuzz challenge, a classic interview question.

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

@@ -13,7 +13,7 @@
       ".meta/example.arr"
     ]
   },
-  "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"
 }

exercises/practice/reverse-string/.docs/instructions.md

@@ -1,7 +1,9 @@
 # Instructions
 
-Reverse a string
+Your task is to reverse a given string.
 
-For example:
-input: "cool"
-output: "looc"
+Some examples:
+
+- Turn `"stressed"` into `"desserts"`.
+- Turn `"strops"` into `"sports"`.
+- Turn `"racecar"` into `"racecar"`.

exercises/practice/reverse-string/.docs/introduction.md

@@ -0,0 +1,5 @@
+# Introduction
+
+Reversing strings (reading them from right to left, rather than from left to right) is a surprisingly common task in programming.
+
+For example, in bioinformatics, reversing the sequence of DNA or RNA strings is often important for various analyses, such as finding complementary strands or identifying palindromic sequences that have biological significance.

exercises/practice/reverse-string/.meta/config.json

@@ -13,7 +13,7 @@
       ".meta/example.arr"
     ]
   },
-  "blurb": "Reverse a string.",
+  "blurb": "Reverse a given string.",
   "source": "Introductory challenge to reverse an input string",
   "source_url": "https://medium.freecodecamp.org/how-to-reverse-a-string-in-javascript-in-3-different-ways-75e4763c68cb"
 }

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/roman-numerals/.docs/introduction.md

@@ -0,0 +1,59 @@
+# Description
+
+Today, most people in the world use Arabic numerals (0–9).
+But if you travelled back two thousand years, you'd find that most Europeans were using Roman numerals instead.
+
+To write a Roman numeral we use the following Latin letters, each of which has a value:
+
+| M    | D   | C   | L   | X   | V   | I   |
+| ---- | --- | --- | --- | --- | --- | --- |
+| 1000 | 500 | 100 | 50  | 10  | 5   | 1   |
+
+A Roman numeral is a sequence of these letters, and its value is the sum of the letters' values.
+For example, `XVIII` has the value 18 (`10 + 5 + 1 + 1 + 1 = 18`).
+
+There's one rule that makes things trickier though, and that's that **the same letter cannot be used more than three times in succession**.
+That means that we can't express numbers such as 4 with the seemingly natural `IIII`.
+Instead, for those numbers, we use a subtraction method between two letters.
+So we think of `4` not as `1 + 1 + 1 + 1` but instead as `5 - 1`.
+And slightly confusingly to our modern thinking, we write the smaller number first.
+This applies only in the following cases: 4 (`IV`), 9 (`IX`), 40 (`XL`), 90 (`XC`), 400 (`CD`) and 900 (`CM`).
+
+Order matters in Roman numerals!
+Letters (and the special compounds above) must be ordered by decreasing value from left to right.
+
+Here are some examples:
+
+```text
+ 105 => CV
+---- => --
+ 100 => C
++  5 =>  V
+```
+
+```text
+ 106 => CVI
+---- => --
+ 100 => C
++  5 =>  V
++  1 =>   I
+```
+
+```text
+ 104 => CIV
+---- => ---
+ 100 => C
++  4 =>  IV
+```
+
+And a final more complex example:
+
+```text
+ 1996 => MCMXCVI
+----- => -------
+ 1000 => M
++ 900 =>  CM
++  90 =>    XC
++   5 =>      V
++   1 =>       I
+```

exercises/practice/roman-numerals/.meta/config.json

@@ -13,7 +13,7 @@
       ".meta/example.arr"
     ]
   },
-  "blurb": "Write a function to convert from normal numbers to Roman Numerals.",
+  "blurb": "Convert modern Arabic numbers into Roman numerals.",
   "source": "The Roman Numeral Kata",
   "source_url": "https://codingdojo.org/kata/RomanNumerals/"
 }

exercises/practice/strain/.meta/config.json

@@ -13,7 +13,7 @@
       ".meta/example.arr"
     ]
   },
-  "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": "http://graysoftinc.com/"
 }