chore: update docs for July 2024

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

@@ -1,6 +1,6 @@
 # Instructions
 
-Write a function that returns the earned points in a single toss of a Darts game.
+Calculate the points scored in a single toss of a Darts game.
 
 [Darts][darts] is a game where players throw darts at a [target][darts-target].
 
@@ -16,7 +16,7 @@ In our particular instance of the game, the target rewards 4 different amounts o
 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][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.
+Given a point in the target (defined by its [Cartesian coordinates][cartesian-coordinates] `x` and `y`, where `x` and `y` are [real][real-numbers]), calculate the correct score earned by a dart landing at that point.
 
 ## Credit
 

exercises/practice/darts/.meta/config.json

@@ -18,6 +18,6 @@
       ".meta/example.h"
     ]
   },
-  "blurb": "Write a function that returns the earned points in a single toss of a Darts game.",
+  "blurb": "Calculate the points scored in a single toss of a Darts game.",
   "source": "Inspired by an exercise created by a professor Della Paolera in Argentina"
 }

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

@@ -1,4 +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.
-The string may also contain other characters, which for the purposes of this exercise should be ignored.
+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/parallel-letter-frequency/.docs/instructions.md

@@ -4,4 +4,4 @@ Count the frequency of letters in texts using parallel computation.
 
 Parallelism is about doing things in parallel that can also be done sequentially.
 A common example is counting the frequency of letters.
-Create a function that returns the total frequency of each letter in a list of texts and that employs parallelism.
+Employ parallelism to calculate the total frequency of each letter in a list of texts.

exercises/practice/pascals-triangle/.docs/instructions.md

@@ -1,14 +1,35 @@
 # Instructions
 
-Compute Pascal's triangle up to a given number of rows.
+Your task is to output the first N rows of Pascal's triangle.
 
-In Pascal's Triangle each number is computed by adding the numbers to the right and left of the current position in the previous row.
+[Pascal's triangle][wikipedia] is a triangular array of positive integers.
+
+In Pascal's triangle, the number of values in a row is equal to its row number (which starts at one).
+Therefore, the first row has one value, the second row has two values, and so on.
+
+The first (topmost) row has a single value: `1`.
+Subsequent rows' values are computed by adding the numbers directly to the right and left of the current position in the previous row.
+
+If the previous row does _not_ have a value to the left or right of the current position (which only happens for the leftmost and rightmost positions), treat that position's value as zero (effectively "ignoring" it in the summation).
+
+## Example
+
+Let's look at the first 5 rows of Pascal's Triangle:
 
 ```text
     1
    1 1
   1 2 1
  1 3 3 1
 1 4 6 4 1
-# ... etc
 ```
+
+The topmost row has one value, which is `1`.
+
+The leftmost and rightmost values have only one preceding position to consider, which is the position to its right respectively to its left.
+With the topmost value being `1`, it follows from this that all the leftmost and rightmost values are also `1`.
+
+The other values all have two positions to consider.
+For example, the fifth row's (`1 4 6 4 1`) middle value is `6`, as the values to its left and right in the preceding row are `3` and `3`:
+
+[wikipedia]: https://en.wikipedia.org/wiki/Pascal%27s_triangle

exercises/practice/pascals-triangle/.docs/introduction.md

@@ -0,0 +1,22 @@
+# Introduction
+
+With the weather being great, you're not looking forward to spending an hour in a classroom.
+Annoyed, you enter the class room, where you notice a strangely satisfying triangle shape on the blackboard.
+Whilst waiting for your math teacher to arrive, you can't help but notice some patterns in the triangle: the outer values are all ones, each subsequent row has one more value than its previous row and the triangle is symmetrical.
+Weird!
+
+Not long after you sit down, your teacher enters the room and explains that this triangle is the famous [Pascal's triangle][wikipedia].
+
+Over the next hour, your teacher reveals some amazing things hidden in this triangle:
+
+- It can be used to compute how many ways you can pick K elements from N values.
+- It contains the Fibonacci sequence.
+- If you color odd and even numbers differently, you get a beautiful pattern called the [Sierpiński triangle][wikipedia-sierpinski-triangle].
+
+The teacher implores you and your classmates to lookup other uses, and assures you that there are lots more!
+At that moment, the school bell rings.
+You realize that for the past hour, you were completely absorbed in learning about Pascal's triangle.
+You quickly grab your laptop from your bag and go outside, ready to enjoy both the sunshine _and_ the wonders of Pascal's triangle.
+
+[wikipedia]: https://en.wikipedia.org/wiki/Pascal%27s_triangle
+[wikipedia-sierpinski-triangle]: https://en.wikipedia.org/wiki/Sierpi%C5%84ski_triangle

exercises/practice/pig-latin/.docs/instructions.md

@@ -19,7 +19,7 @@ For example:
 
 ## Rule 2
 
-If a word begins with a one or more consonants, first move those consonants to the end of the word and then add an `"ay"` sound to the end of the word.
+If a word begins with one or more consonants, first move those consonants to the end of the word and then add an `"ay"` sound to the end of the word.
 
 For example:
 
@@ -33,7 +33,7 @@ If a word starts with zero or more consonants followed by `"qu"`, first move tho
 
 For example:
 
-- `"quick"` -> `"ickqu"` -> `"ay"` (starts with `"qu"`, no preceding consonants)
+- `"quick"` -> `"ickqu"` -> `"ickquay"` (starts with `"qu"`, no preceding consonants)
 - `"square"` -> `"aresqu"` -> `"aresquay"` (starts with one consonant followed by `"qu`")
 
 ## Rule 4

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

exercises/practice/two-bucket/.docs/instructions.md

@@ -11,7 +11,7 @@ There are some rules that your solution must follow:
      b) the second bucket is full
   2. Emptying a bucket and doing nothing to the other.
   3. Filling a bucket and doing nothing to the other.
-- After an action, you may not arrive at a state where the starting bucket is empty and the other bucket is full.
+- After an action, you may not arrive at a state where the initial starting bucket is empty and the other bucket is full.
 
 Your program will take as input:
 

exercises/practice/yacht/.meta/config.json

@@ -16,6 +16,6 @@
     ]
   },
   "blurb": "Score a single throw of dice in the game Yacht.",
-  "source": "James Kilfiger, using wikipedia",
+  "source": "James Kilfiger, using Wikipedia",
   "source_url": "https://en.wikipedia.org/wiki/Yacht_(dice_game)"
 }

exercises/practice/zebra-puzzle/.docs/instructions.md

@@ -1,6 +1,32 @@
 # Instructions
 
-Your task is to solve the ‘Zebra Puzzle’ also known as ‘The Einstein's Puzzle’ but how you do it that depends on you, best way to solve this problem is first you solve it with your pen and paper, it will take time but it will improve your logical thinking and its provide programmatic way to solve this problem.
+Your task is to solve the Zebra Puzzle to find the answer to these two questions:
 
-**!!Spoiler warning!!**
-You can learn more about this problem on [Zebra Puzzle](https://en.wikipedia.org/wiki/Zebra_Puzzle) 
+- Which of the residents drinks water?
+- Who owns the zebra?
+
+## Puzzle
+
+The following 15 statements are all known to be true:
+
+1. There are five houses.
+2. The Englishman lives in the red house.
+3. The Spaniard owns the dog.
+4. The person in the green house drinks coffee.
+5. The Ukrainian drinks tea.
+6. The green house is immediately to the right of the ivory house.
+7. The snail owner likes to go dancing.
+8. The person in the yellow house is a painter.
+9. The person in the middle house drinks milk.
+10. The Norwegian lives in the first house.
+11. The person who enjoys reading lives in the house next to the person with the fox.
+12. The painter's house is next to the house with the horse.
+13. The person who plays football drinks orange juice.
+14. The Japanese person plays chess.
+15. The Norwegian lives next to the blue house.
+
+Additionally, each of the five houses is painted a different color, and their inhabitants are of different national extractions, own different pets, drink different beverages and engage in different hobbies.
+
+~~~~exercism/note
+There are 24 billion (5!⁵ = 24,883,200,000) possible solutions, so try ruling out as many solutions as possible.
+~~~~

exercises/practice/zebra-puzzle/.docs/introduction.md

@@ -1,24 +1,15 @@
-# Instructions
+# Introduction
 
-Solve the zebra puzzle.
+The Zebra Puzzle is a famous logic puzzle in which there are five houses, each painted a different color.
+The houses have different inhabitants, who have different nationalities, own different pets, drink different beverages and enjoy different hobbies.
 
-1. There are five houses.
-2. The Englishman lives in the red house.
-3. The Spaniard owns the dog.
-4. Coffee is drunk in the green house.
-5. The Ukrainian drinks tea.
-6. The green house is immediately to the right of the ivory house.
-7. The Old Gold smoker owns snails.
-8. Kools are smoked in the yellow house.
-9. Milk is drunk in the middle house.
-10. The Norwegian lives in the first house.
-11. The man who smokes Chesterfields lives in the house next to the man with the fox.
-12. Kools are smoked in the house next to the house where the horse is kept.
-13. The Lucky Strike smoker drinks orange juice.
-14. The Japanese smokes Parliaments.
-15. The Norwegian lives next to the blue house.
+To help you solve the puzzle, you're given 15 statements describing the solution.
+However, only by combining the information in _all_ statements will you be able to find the solution to the puzzle.
 
-Each of the five houses is painted a different color, and their inhabitants are of different national extractions, own different pets, drink different beverages and smoke different brands of cigarettes.
+~~~~exercism/note
+The Zebra Puzzle is a [Constraint satisfaction problem (CSP)][constraint-satisfaction-problem].
+In such a problem, you have a set of possible values and a set of constraints that limit which values are valid.
+Another well-known CSP is Sudoku.
 
-Which of the residents drinks water?
-Who owns the zebra?
+[constraint-satisfaction-problem]: https://en.wikipedia.org/wiki/Constraint_satisfaction_problem
+~~~~