Sync exercise instructions (#224)

exercises/practice/allergies/.docs/instructions.md

@@ -2,20 +2,18 @@
 
 Given a person's allergy score, determine whether or not they're allergic to a given item, and their full list of allergies.
 
-An allergy test produces a single numeric score which contains the
-information about all the allergies the person has (that they were
-tested for).
+An allergy test produces a single numeric score which contains the information about all the allergies the person has (that they were tested for).
 
 The list of items (and their value) that were tested are:
 
-* eggs (1)
-* peanuts (2)
-* shellfish (4)
-* strawberries (8)
-* tomatoes (16)
-* chocolate (32)
-* pollen (64)
-* cats (128)
+- eggs (1)
+- peanuts (2)
+- shellfish (4)
+- strawberries (8)
+- tomatoes (16)
+- chocolate (32)
+- pollen (64)
+- cats (128)
 
 So if Tom is allergic to peanuts and chocolate, he gets a score of 34.
 
@@ -24,7 +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.).  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.
+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.

exercises/practice/binary-search/.docs/instructions.md

@@ -11,7 +11,7 @@ Binary search only works when a list has been sorted.
 
 The algorithm looks like this:
 
-- Find the middle element of a *sorted* list and compare it with the item we're looking for.
+- Find the middle element of a _sorted_ list and compare it with the item we're looking for.
 - If the middle element is our item, then we're done!
 - If the middle element is greater than our item, we can eliminate that element and all the elements **after** it.
 - If the middle element is less than our item, we can eliminate that element and all the elements **before** it.

exercises/practice/collatz-conjecture/.docs/instructions.md

@@ -2,10 +2,11 @@
 
 The Collatz Conjecture or 3x+1 problem can be summarized as follows:
 
-Take any positive integer n. If n is even, divide n by 2 to get n / 2. If n is
-odd, multiply n by 3 and add 1 to get 3n + 1. Repeat the process indefinitely.
-The conjecture states that no matter which number you start with, you will
-always reach 1 eventually.
+Take any positive integer n.
+If n is even, divide n by 2 to get n / 2.
+If n is odd, multiply n by 3 and add 1 to get 3n + 1.
+Repeat the process indefinitely.
+The conjecture states that no matter which number you start with, you will always reach 1 eventually.
 
 Given a number n, return the number of steps required to reach 1.
 
@@ -24,4 +25,5 @@ Starting with n = 12, the steps would be as follows:
 8. 2
 9. 1
 
-Resulting in 9 steps. So for input n = 12, the return value would be 9.
+Resulting in 9 steps.
+So for input n = 12, the return value would be 9.

exercises/practice/difference-of-squares/.docs/instructions.md

@@ -8,10 +8,7 @@ The square of the sum of the first ten natural numbers is
 The sum of the squares of the first ten natural numbers is
 1² + 2² + ... + 10² = 385.
 
-Hence the difference between the square of the sum of the first
-ten natural numbers and the sum of the squares of the first ten
-natural numbers is 3025 - 385 = 2640.
+Hence the difference between the square of the sum of the first ten natural numbers and the sum of the squares of the first ten natural numbers is 3025 - 385 = 2640.
 
-You are not expected to discover an efficient solution to this yourself from
-first principles; research is allowed, indeed, encouraged. Finding the best
-algorithm for the problem is a key skill in software engineering.
+You are not expected to discover an efficient solution to this yourself from first principles; research is allowed, indeed, encouraged.
+Finding the best algorithm for the problem is a key skill in software engineering.

exercises/practice/grains/.docs/instructions.md

@@ -1,27 +1,15 @@
 # Instructions
 
-Calculate the number of grains of wheat on a chessboard given that the number
-on each square doubles.
+Calculate the number of grains of wheat on a chessboard given that the number on each square doubles.
 
-There once was a wise servant who saved the life of a prince. The king
-promised to pay whatever the servant could dream up. Knowing that the
-king loved chess, the servant told the king he would like to have grains
-of wheat. One grain on the first square of a chess board, with the number
-of grains doubling on each successive square.
+There once was a wise servant who saved the life of a prince.
+The king promised to pay whatever the servant could dream up.
+Knowing that the king loved chess, the servant told the king he would like to have grains of wheat.
+One grain on the first square of a chess board, with the number of grains doubling on each successive square.
 
 There are 64 squares on a chessboard (where square 1 has one grain, square 2 has two grains, and so on).
 
 Write code that shows:
+
 - how many grains were on a given square, and
 - the total number of grains on the chessboard
-
-## 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:
-
-- Optimize for speed.
-- Optimize for readability.
-
-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?

exercises/practice/hamming/.docs/instructions.md

@@ -2,11 +2,17 @@
 
 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!
+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".
+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. Two strands might look like this:
+We read DNA using the letters C,A,G and T.
+Two strands might look like this:
 
     GAGCCTACTAACGGGAT
     CATCGTAATGACGGCCT
@@ -16,9 +22,6 @@ 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 :)
 
-# Implementation notes
+## Implementation notes
 
-The Hamming distance is only defined for sequences of equal length, so
-an attempt to calculate it between sequences of different lengths should
-not work. The general handling of this situation (e.g., raising an
-exception vs returning a special value) may differ between languages.
+The Hamming distance is only defined for sequences of equal length, so an attempt to calculate it between sequences of different lengths should not work.

exercises/practice/hello-world/.docs/instructions.md

@@ -1,15 +1,16 @@
 # Instructions
 
-The classical introductory exercise. Just say "Hello, World!".
+The classical introductory exercise.
+Just say "Hello, World!".
 
-["Hello, World!"](http://en.wikipedia.org/wiki/%22Hello,_world!%22_program) is
-the traditional first program for beginning programming in a new language
-or environment.
+["Hello, World!"][hello-world] is the traditional first program for beginning programming in a new language or environment.
 
 The objectives are simple:
 
-- Write a function that returns the string "Hello, World!".
+- Modify the provided code so that it produces the string "Hello, World!".
 - Run the test suite and make sure that it succeeds.
 - Submit your solution and check it at the website.
 
 If everything goes well, you will be ready to fetch your first real exercise.
+
+[hello-world]: https://en.wikipedia.org/wiki/%22Hello,_world!%22_program

exercises/practice/isogram/.docs/instructions.md

@@ -2,7 +2,7 @@
 
 Determine if a word or phrase is an isogram.
 
-An isogram (also known as a "nonpattern word") is a word or phrase without a repeating letter, however spaces and hyphens are allowed to appear multiple times.
+An isogram (also known as a "non-pattern word") is a word or phrase without a repeating letter, however spaces and hyphens are allowed to appear multiple times.
 
 Examples of isograms:
 
@@ -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.

exercises/practice/linked-list/.docs/instructions.md

@@ -1,28 +1,26 @@
 # Instructions
 
-Implement a doubly linked list.
+Your team has decided to use a doubly linked list to represent each train route in the schedule.
+Each station along the train's route will be represented by a node in the linked list.
 
-Like an array, a linked list is a simple linear data structure. Several
-common data types can be implemented using linked lists, like queues,
-stacks, and associative arrays.
+You don't need to worry about arrival and departure times at the stations.
+Each station will simply be represented by a number.
 
-A linked list is a collection of data elements called *nodes*. In a
-*singly linked list* each node holds a value and a link to the next node.
-In a *doubly linked list* each node also holds a link to the previous
-node.
+Routes can be extended, adding stations to the beginning or end of a route.
+They can also be shortened by removing stations from the beginning or the end of a route.
 
-You will write an implementation of a doubly linked list. Implement a
-Node to hold a value and pointers to the next and previous nodes. Then
-implement a List which holds references to the first and last node and
-offers an array-like interface for adding and removing items:
+Sometimes a station gets closed down, and in that case the station needs to be removed from the route, even if it is not at the beginning or end of the route.
 
-* `push` (*insert value at back*);
-* `pop` (*remove value at back*);
-* `shift` (*remove value at front*).
-* `unshift` (*insert value at front*);
+The size of a route is measured not by how far the train travels, but by how many stations it stops at.
 
-To keep your implementation simple, the tests will not cover error
-conditions. Specifically: `pop` or `shift` will never be called on an
-empty list.
+~~~~exercism/note
+The linked list is a fundamental data structure in computer science, often used in the implementation of other data structures.
+As the name suggests, it is a list of nodes that are linked together.
+It is a list of "nodes", where each node links to its neighbor or neighbors.
+In a **singly linked list** each node links only to the node that follows it.
+In a **doubly linked list** each node links to both the node that comes before, as well as the node that comes after.
 
-If you want to know more about linked lists, check [Wikipedia](https://en.wikipedia.org/wiki/Linked_list).
+If you want to dig deeper into linked lists, check out [this article][intro-linked-list] that explains it using nice drawings.
+
+[intro-linked-list]: https://medium.com/basecs/whats-a-linked-list-anyway-part-1-d8b7e6508b9d
+~~~~

exercises/practice/linked-list/.docs/introduction.md

@@ -0,0 +1,6 @@
+# Introduction
+
+You are working on a project to develop a train scheduling system for a busy railway network.
+
+You've been asked to develop a prototype for the train routes in the scheduling system.
+Each route consists of a sequence of train stations that a given train stops at.

exercises/practice/matching-brackets/.docs/instructions.md

@@ -1,5 +1,5 @@
 # Instructions
 
-Given a string containing brackets `[]`, braces `{}`, parentheses `()`,
-or any combination thereof, verify that any and all pairs are matched
-and nested correctly.
+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.

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

exercises/practice/pangram/.docs/instructions.md

@@ -5,4 +5,4 @@ Your task is to figure out if a sentence is a pangram.
 A pangram is a sentence using every letter of the alphabet at least once.
 It is case insensitive, so it doesn't matter if a letter is lower-case (e.g. `k`) or upper-case (e.g. `K`).
 
-For this exercise we only use the basic letters used in the English alphabet: `a` to `z`.
+For this exercise, a sentence is a pangram if it contains each of the 26 letters in the English alphabet.

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

exercises/practice/resistor-color-duo/.docs/instructions.md

@@ -29,5 +29,5 @@ The band colors are encoded as follows:
 - White: 9
 
 From the example above:
-brown-green should return 15
+brown-green should return 15, and
 brown-green-violet should return 15 too, ignoring the third color.

exercises/practice/resistor-color/.docs/instructions.md

@@ -3,8 +3,8 @@
 If you want to build something using a Raspberry Pi, you'll probably use _resistors_.
 For this exercise, you need to know two things about them:
 
-* Each resistor has a resistance value.
-* Resistors are small - so small in fact that if you printed the resistance value on them, it would be hard to read.
+- Each resistor has a resistance value.
+- Resistors are small - so small in fact that if you printed the resistance value on them, it would be hard to read.
 
 To get around this problem, manufacturers print color-coded bands onto the resistors to denote their resistance values.
 Each band has a position and a numeric value.
@@ -27,9 +27,13 @@ These colors are encoded as follows:
 - White: 9
 
 The goal of this exercise is to create a way:
+
 - to look up the numerical value associated with a particular color band
 - to list the different band colors
 
-Mnemonics map the colors to the numbers, that, when stored as an array, happen to map to their index in the array: Better Be Right Or Your Great Big Values Go Wrong.
+Mnemonics map the colors to the numbers, that, when stored as an array, happen to map to their index in the array:
+Better Be Right Or Your Great Big Values Go Wrong.
+
+More information on the color encoding of resistors can be found in the [Electronic color code Wikipedia article][e-color-code].
 
-More information on the color encoding of resistors can be found in the [Electronic color code Wikipedia article](https://en.wikipedia.org/wiki/Electronic_color_code)
+[e-color-code]: https://en.wikipedia.org/wiki/Electronic_color_code

exercises/practice/rotational-cipher/.docs/instructions.md

@@ -2,11 +2,9 @@
 
 Create an implementation of the rotational cipher, also sometimes called the Caesar cipher.
 
-The Caesar cipher is a simple shift cipher that relies on
-transposing all the letters in the alphabet using an integer key
-between `0` and `26`. Using a key of `0` or `26` will always yield
-the same output due to modular arithmetic. The letter is shifted
-for as many values as the value of the key.
+The Caesar cipher is a simple shift cipher that relies on transposing all the letters in the alphabet using an integer key between `0` and `26`.
+Using a key of `0` or `26` will always yield the same output due to modular arithmetic.
+The letter is shifted for as many values as the value of the key.
 
 The general notation for rotational ciphers is `ROT + <key>`.
 The most commonly used rotational cipher is `ROT13`.
@@ -24,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.`

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