Update docs (#96)

exercises/practice/armstrong-numbers/.docs/instructions.md

@@ -1,6 +1,6 @@
 # Instructions
 
-An [Armstrong number](https://en.wikipedia.org/wiki/Narcissistic_number) is a number that is the sum of its own digits each raised to the power of the number of digits.
+An [Armstrong number][armstrong-number] is a number that is the sum of its own digits each raised to the power of the number of digits.
 
 For example:
 
@@ -10,3 +10,5 @@ For example:
 - 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.
+
+[armstrong-number]: https://en.wikipedia.org/wiki/Narcissistic_number

exercises/practice/bob/.docs/instructions.md

@@ -1,16 +1,19 @@
-# Description
+# Instructions
 
-Bob is a lackadaisical teenager. In conversation, his responses are very limited.
+Your task is to determine what Bob will reply to someone when they say something to him or ask him a question.
 
-Bob answers 'Sure.' if you ask him a question, such as "How are you?".
+Bob only ever answers one of five things:
 
-He answers 'Whoa, chill out!' if you YELL AT HIM (in all capitals).
-
-He answers 'Calm down, I know what I'm doing!' if you yell a question at him.
-
-He says 'Fine. Be that way!' if you address him without actually saying
-anything.
-
-He answers 'Whatever.' to anything else.
-
-Bob's conversational partner is a purist when it comes to written communication and always follows normal rules regarding sentence punctuation in English.
+- **"Sure."**
+  This is his response if you ask him a question, such as "How are you?"
+  The convention used for questions is that it ends with a question mark.
+- **"Whoa, chill out!"**
+  This is his answer if you YELL AT HIM.
+  The convention used for yelling is ALL CAPITAL LETTERS.
+- **"Calm down, I know what I'm doing!"**
+  This is what he says if you yell a question at him.
+- **"Fine. Be that way!"**
+  This is how he responds to silence.
+  The convention used for silence is nothing, or various combinations of whitespace characters.
+- **"Whatever."**
+  This is what he answers to anything else.

exercises/practice/bob/.docs/introduction.md

@@ -0,0 +1,10 @@
+# Introduction
+
+Bob is a [lackadaisical][] teenager.
+He likes to think that he's very cool.
+And he definitely doesn't get excited about things.
+That wouldn't be cool.
+
+When people talk to him, his responses are pretty limited.
+
+[lackadaisical]: https://www.collinsdictionary.com/dictionary/english/lackadaisical

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

@@ -2,12 +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.
-
-## Task
+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.
 
@@ -26,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/darts/.docs/instructions.md

@@ -1,17 +1,23 @@
-# Description
+# Instructions
 
 Write a function that returns the earned points in a single toss of a Darts game.
 
-[Darts](https://en.wikipedia.org/wiki/Darts) is a game where players
-throw darts at a [target](https://en.wikipedia.org/wiki/Darts#/media/File:Darts_in_a_dartboard.jpg).
+[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:
 
-* 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.
-* If the dart lands in the inner circle of the target, player earns 10 points.
+- 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.
+- If the dart lands in the inner circle of the target, player earns 10 points.
 
-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](http://mathworld.wolfram.com/ConcentricCircles.html)) defined by the coordinates (0, 0).
+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](https://www.mathsisfun.com/data/cartesian-coordinates.html) `x` and `y`, where `x` and `y` are [real](https://www.mathsisfun.com/numbers/real-numbers.html)), returns the correct amount earned by a dart landing at that point.
+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.
+
+[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

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

@@ -2,18 +2,13 @@
 
 Find the difference between the square of the sum and the sum of the squares of the first N natural numbers.
 
-## Task
-
 The square of the sum of the first ten natural numbers is
 (1 + 2 + ... + 10)² = 55² = 3025.
 
 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/hamming/.docs/instructions.md

@@ -1,14 +1,18 @@
 # Instructions
 
-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".
+Calculate the Hamming Distance between two DNA strands.
 
-## Task
+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!
 
-Calculate the Hamming Distance between two DNA strands.
+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
@@ -20,6 +24,4 @@ The Hamming Distance is useful for lots of things in science, not just biology,
 
 ## 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 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,10 +1,9 @@
 # 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:
 
@@ -13,3 +12,5 @@ The objectives are simple:
 - 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

@@ -1,4 +1,4 @@
-# Description
+# Instructions
 
 Determine if a word or phrase is an isogram.
 

exercises/practice/leap/.docs/instructions.md

@@ -1,4 +1,4 @@
-# Description
+# Instructions
 
 Given a year, report if it is a leap year.
 
@@ -10,15 +10,13 @@ on every year that is evenly divisible by 4
     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.
+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!
+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].
+For a delightful, four minute explanation of the whole leap year phenomenon, go watch [this youtube video][video].
 
-[video]: http://www.youtube.com/watch?v=xX96xng7sAE
+[video]: https://www.youtube.com/watch?v=xX96xng7sAE

exercises/practice/luhn/.docs/instructions.md

@@ -1,36 +1,32 @@
 # Instructions
 
-The [Luhn algorithm](https://en.wikipedia.org/wiki/Luhn_algorithm) is
-a simple checksum formula used to validate a variety of identification
-numbers, such as credit card numbers and Canadian Social Insurance
-Numbers.
+Given a number determine whether or not it is valid per the Luhn formula.
 
-## Task
+The [Luhn algorithm][luhn] is a simple checksum formula used to validate a variety of identification numbers, such as credit card numbers and Canadian Social Insurance Numbers.
 
-Given a number determine whether or not it is valid per the Luhn formula.
 The task is to check if a given string is valid.
 
 ## Validating a Number
 
-Strings of length 1 or less are not valid. Spaces are allowed in the input,
-but they should be stripped before checking. All other non-digit characters
-are disallowed.
+Strings of length 1 or less are not valid.
+Spaces are allowed in the input, but they should be stripped before checking.
+All other non-digit characters are disallowed.
 
 ### Example 1: valid credit card number
 
 ```text
 4539 3195 0343 6467
 ```
 
-The first step of the Luhn algorithm is to double every second digit,
-starting from the right. We will be doubling
+The first step of the Luhn algorithm is to double every second digit, starting from the right.
+We will be doubling
 
 ```text
 4_3_ 3_9_ 0_4_ 6_6_
 ```
 
-If doubling the number results in a number greater than 9 then subtract 9
-from the product. The results of our doubling:
+If doubling the number results in a number greater than 9 then subtract 9 from the product.
+The results of our doubling:
 
 ```text
 8569 6195 0383 3437
@@ -42,7 +38,8 @@ Then sum all of the digits:
 8+5+6+9+6+1+9+5+0+3+8+3+3+4+3+7 = 80
 ```
 
-If the sum is evenly divisible by 10, then the number is valid. This number is valid!
+If the sum is evenly divisible by 10, then the number is valid.
+This number is valid!
 
 ### Example 2: invalid credit card number
 
@@ -63,3 +60,5 @@ Sum the digits
 ```
 
 57 is not evenly divisible by 10, so this number is not valid.
+
+[luhn]: https://en.wikipedia.org/wiki/Luhn_algorithm

exercises/practice/nucleotide-count/.docs/instructions.md

@@ -1,17 +1,17 @@
 # Instructions
 
-Each of us inherits from our biological parents a set of chemical instructions known as DNA that influence how our bodies are constructed. All known life depends on DNA!
+Each of us inherits from our biological parents a set of chemical instructions known as DNA that influence how our bodies are constructed.
+All known life depends on DNA!
 
 > Note: You do not need to understand anything about nucleotides or DNA to complete this exercise.
 
-DNA is a long chain of other chemicals and the most important are the four nucleotides, adenine, cytosine, guanine and thymine. A single DNA chain can contain billions of these four nucleotides and the order in which they occur is important!
+DNA is a long chain of other chemicals and the most important are the four nucleotides, adenine, cytosine, guanine and thymine.
+A single DNA chain can contain billions of these four nucleotides and the order in which they occur is important!
 We call the order of these nucleotides in a bit of DNA a "DNA sequence".
 
 We represent a DNA sequence as an ordered collection of these four nucleotides and a common way to do that is with a string of characters such as "ATTACG" for a DNA sequence of 6 nucleotides.
 'A' for adenine, 'C' for cytosine, 'G' for guanine, and 'T' for thymine.
 
-## Task
-
 Given a string representing a DNA sequence, count how many of each nucleotide is present.
 If the string contains characters that aren't A, C, G, or T then it is invalid and you should signal an error.
 

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

@@ -7,10 +7,10 @@ To give a comprehensive sense of the font, the random sentences should use **all
 They're running a competition to get suggestions for sentences that they can use.
 You're in charge of checking the submissions to see if they are valid.
 
-```exercism/note
+~~~~exercism/note
 Pangram comes from Greek, παν γράμμα, pan gramma, which means "every letter".
 
 The best known English pangram is:
 
 > The quick brown fox jumps over the lazy dog.
-```
+~~~~

exercises/practice/queen-attack/.docs/instructions.md

@@ -1,25 +1,25 @@
-# Description
+# Instructions
 
 Given the position of two queens on a chess board, indicate whether or not they are positioned so that they can attack each other.
 
 In the game of chess, a queen can attack pieces which are on the same row, column, or diagonal.
 
 A chessboard can be represented by an 8 by 8 array.
 
-So if you are told the white queen is at (zero-indexed) row 4, column 2 and the black queen at (zero-indexed) row 1, column 5 then you know that the set-up is like so:
+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
-  0 1 2 3 4 5 6 7
+  a b c d e f g h
+8 _ _ _ _ _ _ _ _ 8
 7 _ _ _ _ _ _ _ _ 7
 6 _ _ _ _ _ _ _ _ 6
-5 _ _ _ _ _ _ _ _ 5
-4 _ _ W _ _ _ _ _ 4
+5 _ _ W _ _ _ _ _ 5
+4 _ _ _ _ _ _ _ _ 4
 3 _ _ _ _ _ _ _ _ 3
-2 _ _ _ _ _ _ _ _ 2
-1 _ _ _ _ _ B _ _ 1
-0 _ _ _ _ _ _ _ _ 0
-  0 1 2 3 4 5 6 7
+2 _ _ _ _ _ B _ _ 2
+1 _ _ _ _ _ _ _ _ 1
+  a b c d e f g h
 ```
 
-You are also be able to answer whether the queens can attack each other.
+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.

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

@@ -1,10 +1,8 @@
 # Instructions
 
-A variation on FizzBuzz, a famous technical interview question that is intended to weed out potential candidates.
-
-## Task
-
-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](https://en.wikipedia.org/wiki/Modulo_operation).
+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].
 
 The rules of `raindrops` are that if a given number:
 
@@ -18,3 +16,5 @@ The rules of `raindrops` are that if a given number:
 - 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".
+
+[modulo]: https://en.wikipedia.org/wiki/Modulo_operation