diff --git a/bin/generate b/bin/generate
index 070b63cbba..65ce7e51a5 100755
--- a/bin/generate
+++ b/bin/generate
@@ -3,7 +3,7 @@
 require_relative '../lib/helper'
 require 'generator'
 
-paths = Generator::Paths.new(track: EXERCISM_RUBY_ROOT, metadata: METADATA_REPOSITORY_PATH)
+paths = Generator::Paths.new(track: EXERCISM_RUBY_ROOT, docs: EXERCISM_RUBY_DOCS, metadata: METADATA_REPOSITORY_PATH)
 
 generators = Generator::CommandLine.new(paths).parse(ARGV)
 exit 1 unless generators
diff --git a/docs/EXERCISE_README_INSERT.md b/docs/EXERCISE_README_INSERT.md
index b946eeb289..1ff48ed22a 100644
--- a/docs/EXERCISE_README_INSERT.md
+++ b/docs/EXERCISE_README_INSERT.md
@@ -22,3 +22,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
+## Submitting Incomplete Solutions
+It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/acronym/README.md b/exercises/acronym/README.md
index 7fbb051222..2d7296628f 100644
--- a/exercises/acronym/README.md
+++ b/exercises/acronym/README.md
@@ -1,5 +1,3 @@
-# Acronym
-
 Convert a phrase to its acronym.
 
 Techies love their TLA (Three Letter Acronyms)!
@@ -32,10 +30,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Julien Vanier [https://github.com/monkbroc](https://github.com/monkbroc)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/all-your-base/README.md b/exercises/all-your-base/README.md
index 865be3e448..ba959230e4 100644
--- a/exercises/all-your-base/README.md
+++ b/exercises/all-your-base/README.md
@@ -1,5 +1,3 @@
-# All Your Base
-
 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**,
@@ -55,7 +53,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/alphametics/README.md b/exercises/alphametics/README.md
index a14369099f..00b0782fe1 100644
--- a/exercises/alphametics/README.md
+++ b/exercises/alphametics/README.md
@@ -1,5 +1,3 @@
-# Alphametics
-
 Write a function to solve alphametics puzzles.
 
 [Alphametics](https://en.wikipedia.org/wiki/Alphametics) is a puzzle where
@@ -55,7 +53,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/anagram/README.md b/exercises/anagram/README.md
index 15857df784..24357083fd 100644
--- a/exercises/anagram/README.md
+++ b/exercises/anagram/README.md
@@ -1,5 +1,3 @@
-# Anagram
-
 Given a word and a list of possible anagrams, select the correct sublist.
 
 Given `"listen"` and a list of candidates like `"enlists" "google"
@@ -30,10 +28,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Inspired by the Extreme Startup game [https://github.com/rchatley/extreme_startup](https://github.com/rchatley/extreme_startup)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/beer-song/README.md b/exercises/beer-song/README.md
index 1d603c268b..e9bc8baa11 100644
--- a/exercises/beer-song/README.md
+++ b/exercises/beer-song/README.md
@@ -1,5 +1,3 @@
-# Beer Song
-
 Produce the lyrics to that beloved classic, that field-trip favorite: 99 Bottles of Beer on the Wall.
 
 Note that not all verses are identical.
@@ -344,10 +342,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Learn to Program by Chris Pine [http://pine.fm/LearnToProgram/?Chapter=06](http://pine.fm/LearnToProgram/?Chapter=06)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/binary/README.md b/exercises/binary/README.md
index 8b66f4505b..e15e5f6457 100644
--- a/exercises/binary/README.md
+++ b/exercises/binary/README.md
@@ -1,5 +1,3 @@
-# Binary
-
 Convert a binary number, represented as a string (e.g. '101010'), to its decimal equivalent using first principles.
 
 Implement binary to decimal conversion. Given a binary input
@@ -52,10 +50,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-All of Computer Science [http://www.wolframalpha.com/input/?i=binary&a=*C.binary-_*MathWorld-](http://www.wolframalpha.com/input/?i=binary&a=*C.binary-_*MathWorld-)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/bob/README.md b/exercises/bob/README.md
index 9019bf4d85..168ab232ec 100644
--- a/exercises/bob/README.md
+++ b/exercises/bob/README.md
@@ -1,5 +1,3 @@
-# Bob
-
 Bob is a lackadaisical teenager. In conversation, his responses are very limited.
 
 Bob answers 'Sure.' if you ask him a question.
@@ -35,10 +33,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Inspired by the 'Deaf Grandma' exercise in Chris Pine's Learn to Program tutorial. [http://pine.fm/LearnToProgram/?Chapter=06](http://pine.fm/LearnToProgram/?Chapter=06)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/bowling/README.md b/exercises/bowling/README.md
index 1dc31916c5..6447837c09 100644
--- a/exercises/bowling/README.md
+++ b/exercises/bowling/README.md
@@ -1,5 +1,3 @@
-# Bowling
-
 Score a bowling game.
 
 Bowling is game where players roll a heavy ball to knock down pins
@@ -70,10 +68,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-The Bowling Game Kata at but UncleBob [http://butunclebob.com/ArticleS.UncleBob.TheBowlingGameKata](http://butunclebob.com/ArticleS.UncleBob.TheBowlingGameKata)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/bracket-push/README.md b/exercises/bracket-push/README.md
index 34d13def0a..8fb701914b 100644
--- a/exercises/bracket-push/README.md
+++ b/exercises/bracket-push/README.md
@@ -1,5 +1,3 @@
-# Bracket Push
-
 Given a string containing brackets `[]`, braces `{}` and parentheses `()`,
 verify that all the pairs are matched and nested correctly.
 
@@ -27,10 +25,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Ginna Baker
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/change/README.md b/exercises/change/README.md
new file mode 100644
index 0000000000..8e459acc0a
--- /dev/null
+++ b/exercises/change/README.md
@@ -0,0 +1,42 @@
+Correctly determine the fewest number of coins to be given to a customer such
+that the sum of the coins' value would equal the correct amount of change.
+
+## For example
+
+- An input of 15 with [1, 5, 10, 25, 100] should return one nickel (5)
+  and one dime (10) or [0, 1, 1, 0, 0]
+- An input of 40 with [1, 5, 10, 25, 100] should return one nickel (5)
+  and one dime (10) and one quarter (25) or [0, 1, 1, 1, 0]
+
+## Edge cases
+
+- Does your algorithm work for any given set of coins?
+- Can you ask for negative change?
+- Can you ask for a change value smaller than the smallest coin value?
+
+* * * *
+
+For installation and learning resources, refer to the
+[exercism help page](http://exercism.io/languages/ruby).
+
+For running the tests provided, you will need the Minitest gem. Open a
+terminal window and run the following command to install minitest:
+
+    gem install minitest
+
+If you would like color output, you can `require 'minitest/pride'` in
+the test file, or note the alternative instruction, below, for running
+the test file.
+
+In order to run the test, you can run the test file from the exercise
+directory. For example, if the test suite is called
+`hello_world_test.rb`, you can run the following command:
+
+    ruby hello_world_test.rb
+
+To include color from the command line:
+
+    ruby -r minitest/pride hello_world_test.rb
+
+## Submitting Incomplete Solutions
+It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/clock/README.md b/exercises/clock/README.md
index 590d0150f5..b10ae527d7 100644
--- a/exercises/clock/README.md
+++ b/exercises/clock/README.md
@@ -1,5 +1,3 @@
-# Clock
-
 Implement a clock that handles times without dates.
 
 You should be able to add and subtract minutes to it.
@@ -30,10 +28,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Pairing session with Erin Drummond [https://twitter.com/ebdrummond](https://twitter.com/ebdrummond)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/collatz-conjecture/README.md b/exercises/collatz-conjecture/README.md
index b8fe3fae04..7dcc402be6 100644
--- a/exercises/collatz-conjecture/README.md
+++ b/exercises/collatz-conjecture/README.md
@@ -1,5 +1,3 @@
-# Collatz Conjecture
-
 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
@@ -50,10 +48,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-An unsolved problem in mathematics named after mathematician Lothar Collatz [https://en.wikipedia.org/wiki/3x_%2B_1_problem](https://en.wikipedia.org/wiki/3x_%2B_1_problem)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/connect/README.md b/exercises/connect/README.md
index aae91bfbc5..eef3c42875 100644
--- a/exercises/connect/README.md
+++ b/exercises/connect/README.md
@@ -1,5 +1,3 @@
-# Connect
-
 Compute the result for a game of Hex / Polygon.
 
 The abstract boardgame known as
@@ -54,7 +52,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/custom-set/README.md b/exercises/custom-set/README.md
index 3e4de704a3..097ad1fc4f 100644
--- a/exercises/custom-set/README.md
+++ b/exercises/custom-set/README.md
@@ -1,5 +1,3 @@
-# Custom Set
-
 Create a custom set type.
 
 Sometimes it is necessary to define a custom data structure of some
@@ -31,7 +29,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/difference-of-squares/README.md b/exercises/difference-of-squares/README.md
index 62728718a0..5a48d4e81a 100644
--- a/exercises/difference-of-squares/README.md
+++ b/exercises/difference-of-squares/README.md
@@ -1,5 +1,3 @@
-# Difference Of Squares
-
 Find the difference between the square of the sum and the sum of the squares of the first N natural numbers.
 
 The square of the sum of the first ten natural numbers is
@@ -36,10 +34,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Problem 6 at Project Euler [http://projecteuler.net/problem=6](http://projecteuler.net/problem=6)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/dominoes/README.md b/exercises/dominoes/README.md
index 14f666d6d5..8e8c956a48 100644
--- a/exercises/dominoes/README.md
+++ b/exercises/dominoes/README.md
@@ -1,5 +1,3 @@
-# Dominoes
-
 Make a chain of dominoes.
 
 Compute a way to order a given set of dominoes in such a way that they form a
@@ -38,7 +36,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/etl/README.md b/exercises/etl/README.md
index b7dbc63635..f9de1ff53a 100644
--- a/exercises/etl/README.md
+++ b/exercises/etl/README.md
@@ -1,5 +1,3 @@
-# Etl
-
 We are going to do the `Transform` step of an Extract-Transform-Load.
 
 ### ETL
@@ -68,10 +66,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-The Jumpstart Lab team [http://jumpstartlab.com](http://jumpstartlab.com)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/gigasecond/README.md b/exercises/gigasecond/README.md
index c4fdc48475..4517741f80 100644
--- a/exercises/gigasecond/README.md
+++ b/exercises/gigasecond/README.md
@@ -1,5 +1,3 @@
-# Gigasecond
-
 Calculate the moment when someone has lived for 10^9 seconds.
 
 A gigasecond is 10^9 (1,000,000,000) seconds.
@@ -28,10 +26,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Chapter 9 in Chris Pine's online Learn to Program tutorial. [http://pine.fm/LearnToProgram/?Chapter=09](http://pine.fm/LearnToProgram/?Chapter=09)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/grains/README.md b/exercises/grains/README.md
index b78c06e78c..c0be805ca1 100644
--- a/exercises/grains/README.md
+++ b/exercises/grains/README.md
@@ -1,5 +1,3 @@
-# Grains
-
 Calculate the number of grains of wheat on a chessboard given that the number
 on each square doubles.
 
@@ -51,10 +49,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-JavaRanch Cattle Drive, exercise 6 [http://www.javaranch.com/grains.jsp](http://www.javaranch.com/grains.jsp)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/hamming/README.md b/exercises/hamming/README.md
index 936cbdf2c4..6e7246183d 100644
--- a/exercises/hamming/README.md
+++ b/exercises/hamming/README.md
@@ -1,5 +1,3 @@
-# Hamming
-
 Calculate the Hamming difference between two DNA strands.
 
 A mutation is simply a mistake that occurs during the creation or
@@ -59,10 +57,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-The Calculating Point Mutations problem at Rosalind [http://rosalind.info/problems/hamm/](http://rosalind.info/problems/hamm/)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/hello-world/README.md b/exercises/hello-world/README.md
index 335b523b8d..54d002d127 100644
--- a/exercises/hello-world/README.md
+++ b/exercises/hello-world/README.md
@@ -1,5 +1,3 @@
-# Hello World
-
 The classical introductory exercise. Just say "Hello, World!".
 
 ["Hello, World!"](http://en.wikipedia.org/wiki/%22Hello,_world!%22_program) is
@@ -38,10 +36,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-This is an exercise to introduce users to using Exercism [http://en.wikipedia.org/wiki/%22Hello,_world!%22_program](http://en.wikipedia.org/wiki/%22Hello,_world!%22_program)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/isogram/README.md b/exercises/isogram/README.md
index 1dfffd2185..b6b1834e79 100644
--- a/exercises/isogram/README.md
+++ b/exercises/isogram/README.md
@@ -1,5 +1,3 @@
-# Isogram
-
 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.
@@ -36,10 +34,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Wikipedia [https://en.wikipedia.org/wiki/Isogram](https://en.wikipedia.org/wiki/Isogram)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/largest-series-product/README.md b/exercises/largest-series-product/README.md
index f9ea37d478..e459fec2fb 100644
--- a/exercises/largest-series-product/README.md
+++ b/exercises/largest-series-product/README.md
@@ -1,5 +1,3 @@
-# Largest Series Product
-
 Given a string of digits, calculate the largest product for a contiguous
 substring of digits of length n.
 
@@ -37,10 +35,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-A variation on Problem 8 at Project Euler [http://projecteuler.net/problem=8](http://projecteuler.net/problem=8)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/leap/README.md b/exercises/leap/README.md
index bc5e5bf9dc..228a95b0f9 100644
--- a/exercises/leap/README.md
+++ b/exercises/leap/README.md
@@ -1,5 +1,3 @@
-# Leap
-
 Given a year, report if it is a leap year.
 
 The tricky thing here is that a leap year in the Gregorian calendar occurs:
@@ -50,10 +48,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-JavaRanch Cattle Drive, exercise 3 [http://www.javaranch.com/leap.jsp](http://www.javaranch.com/leap.jsp)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/luhn/README.md b/exercises/luhn/README.md
index 830097097f..c98fcac7f1 100644
--- a/exercises/luhn/README.md
+++ b/exercises/luhn/README.md
@@ -1,5 +1,3 @@
-# Luhn
-
 Given a number determine whether or not it is valid per the Luhn formula.
 
 The [Luhn algorithm](https://en.wikipedia.org/wiki/Luhn_algorithm) is
@@ -88,10 +86,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-The Luhn Algorithm on Wikipedia [http://en.wikipedia.org/wiki/Luhn_algorithm](http://en.wikipedia.org/wiki/Luhn_algorithm)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/nth-prime/README.md b/exercises/nth-prime/README.md
index cf698a9295..9a9825ca02 100644
--- a/exercises/nth-prime/README.md
+++ b/exercises/nth-prime/README.md
@@ -1,5 +1,3 @@
-# Nth Prime
-
 Given a number n, determine what the nth prime is.
 
 By listing the first six prime numbers: 2, 3, 5, 7, 11, and 13, we can see that
@@ -32,10 +30,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-A variation on Problem 7 at Project Euler [http://projecteuler.net/problem=7](http://projecteuler.net/problem=7)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/ocr-numbers/README.md b/exercises/ocr-numbers/README.md
index e201a94f15..4d2ebe2cee 100644
--- a/exercises/ocr-numbers/README.md
+++ b/exercises/ocr-numbers/README.md
@@ -1,5 +1,3 @@
-# Ocr Numbers
-
 Given a 3 x 4 grid of pipes, underscores, and spaces, determine which number is
 represented, or whether it is garbled.
 
@@ -102,10 +100,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Inspired by the Bank OCR kata [http://codingdojo.org/cgi-bin/wiki.pl?KataBankOCR](http://codingdojo.org/cgi-bin/wiki.pl?KataBankOCR)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/pangram/README.md b/exercises/pangram/README.md
index 50d954d7ca..d82f393858 100644
--- a/exercises/pangram/README.md
+++ b/exercises/pangram/README.md
@@ -1,5 +1,3 @@
-# Pangram
-
 Determine if a sentence is a pangram. A pangram (Greek: παν γράμμα, pan gramma,
 "every letter") is a sentence using every letter of the alphabet at least once.
 The best known English pangram is: 
@@ -32,10 +30,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Wikipedia [https://en.wikipedia.org/wiki/Pangram](https://en.wikipedia.org/wiki/Pangram)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/phone-number/README.md b/exercises/phone-number/README.md
index 0b4d323211..511388b168 100644
--- a/exercises/phone-number/README.md
+++ b/exercises/phone-number/README.md
@@ -1,5 +1,3 @@
-# Phone Number
-
 Clean up user-entered phone numbers so that they can be sent SMS messages.
 
 The **North American Numbering Plan (NANP)** is a telephone numbering system used by many countries in North America like the United States, Canada or Bermuda. All NANP-countries share the same international country code: `1`.
@@ -51,10 +49,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Event Manager by JumpstartLab [http://tutorials.jumpstartlab.com/projects/eventmanager.html](http://tutorials.jumpstartlab.com/projects/eventmanager.html)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/pig-latin/README.md b/exercises/pig-latin/README.md
index 2633718104..57db2bfab2 100644
--- a/exercises/pig-latin/README.md
+++ b/exercises/pig-latin/README.md
@@ -1,5 +1,3 @@
-# Pig Latin
-
 Implement a program that translates from English to Pig Latin.
 
 Pig Latin is a made-up children's language that's intended to be
@@ -41,10 +39,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-The Pig Latin exercise at Test First Teaching by Ultrasaurus [https://github.com/ultrasaurus/test-first-teaching/blob/master/learn_ruby/pig_latin/](https://github.com/ultrasaurus/test-first-teaching/blob/master/learn_ruby/pig_latin/)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/queen-attack/README.md b/exercises/queen-attack/README.md
index 506c6441f6..726ba4b30b 100644
--- a/exercises/queen-attack/README.md
+++ b/exercises/queen-attack/README.md
@@ -1,5 +1,3 @@
-# Queen Attack
-
 Given the position of two queens on a chess board, indicate whether or not they
 are positioned so that they can attack each other.
 
@@ -50,10 +48,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-J Dalbey's Programming Practice problems [http://users.csc.calpoly.edu/~jdalbey/103/Projects/ProgrammingPractice.html](http://users.csc.calpoly.edu/~jdalbey/103/Projects/ProgrammingPractice.html)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/raindrops/README.md b/exercises/raindrops/README.md
index 8cf930774c..3fa7843a21 100644
--- a/exercises/raindrops/README.md
+++ b/exercises/raindrops/README.md
@@ -1,5 +1,3 @@
-# Raindrops
-
 Convert a number to a string, the contents of which depend on the number's factors.
 
 - If the number has 3 as a factor, output 'Pling'.
@@ -41,10 +39,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-A variation on a famous interview question intended to weed out potential candidates. [http://jumpstartlab.com](http://jumpstartlab.com)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/rna-transcription/README.md b/exercises/rna-transcription/README.md
index e2929a2340..d27e048b89 100644
--- a/exercises/rna-transcription/README.md
+++ b/exercises/rna-transcription/README.md
@@ -1,5 +1,3 @@
-# Rna Transcription
-
 Given a DNA strand, return its RNA complement (per RNA transcription).
 
 Both DNA and RNA strands are a sequence of nucleotides.
@@ -42,10 +40,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Rosalind [http://rosalind.info/problems/rna](http://rosalind.info/problems/rna)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/roman-numerals/README.md b/exercises/roman-numerals/README.md
index 29eae2e634..739f1260cc 100644
--- a/exercises/roman-numerals/README.md
+++ b/exercises/roman-numerals/README.md
@@ -1,5 +1,3 @@
-# Roman Numerals
-
 Write a function to convert from normal numbers to Roman Numerals.
 
 The Romans were a clever bunch. They conquered most of Europe and ruled
@@ -66,10 +64,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-The Roman Numeral Kata [http://codingdojo.org/cgi-bin/index.pl?KataRomanNumerals](http://codingdojo.org/cgi-bin/index.pl?KataRomanNumerals)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/rotational-cipher/README.md b/exercises/rotational-cipher/README.md
new file mode 100644
index 0000000000..5a238b181d
--- /dev/null
+++ b/exercises/rotational-cipher/README.md
@@ -0,0 +1,55 @@
+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 general notation for rotational ciphers is `ROT + <key>`.
+The most commonly used rotational cipher is `ROT13`.
+
+A `ROT13` on the Latin alphabet would be as follows:
+
+```plain
+Plain:  abcdefghijklmnopqrstuvwxyz
+Cipher: nopqrstuvwxyzabcdefghijklm
+```
+
+It is stronger than the Atbash cipher because it has 27 possible keys, and 25 usable keys.
+
+Ciphertext is written out in the same formatting as the input including spaces and punctuation.
+
+## Examples
+- 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.`
+
+* * * *
+
+For installation and learning resources, refer to the
+[exercism help page](http://exercism.io/languages/ruby).
+
+For running the tests provided, you will need the Minitest gem. Open a
+terminal window and run the following command to install minitest:
+
+    gem install minitest
+
+If you would like color output, you can `require 'minitest/pride'` in
+the test file, or note the alternative instruction, below, for running
+the test file.
+
+In order to run the test, you can run the test file from the exercise
+directory. For example, if the test suite is called
+`hello_world_test.rb`, you can run the following command:
+
+    ruby hello_world_test.rb
+
+To include color from the command line:
+
+    ruby -r minitest/pride hello_world_test.rb
+
+## Submitting Incomplete Solutions
+It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/run-length-encoding/README.md b/exercises/run-length-encoding/README.md
index 3fe7134a83..d2ad10abad 100644
--- a/exercises/run-length-encoding/README.md
+++ b/exercises/run-length-encoding/README.md
@@ -1,5 +1,3 @@
-# Run Length Encoding
-
 Implement run-length encoding and decoding.
 
 Run-length encoding (RLE) is a simple form of data compression, where runs
@@ -47,10 +45,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Wikipedia [https://en.wikipedia.org/wiki/Run-length_encoding](https://en.wikipedia.org/wiki/Run-length_encoding)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/say/README.md b/exercises/say/README.md
index b61d98fd03..2443af225f 100644
--- a/exercises/say/README.md
+++ b/exercises/say/README.md
@@ -1,5 +1,3 @@
-# Say
-
 Given a number from 0 to 999,999,999,999, spell out that number in English.
 
 ## Step 1
@@ -86,10 +84,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-A variation on JavaRanch CattleDrive, exercise 4a [http://www.javaranch.com/say.jsp](http://www.javaranch.com/say.jsp)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/sieve/README.md b/exercises/sieve/README.md
index 8be49d6143..b2b560c0ac 100644
--- a/exercises/sieve/README.md
+++ b/exercises/sieve/README.md
@@ -1,5 +1,3 @@
-# Sieve
-
 Use the Sieve of Eratosthenes to find all the primes from 2 up to a given
 number.
 
@@ -51,10 +49,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Sieve of Eratosthenes at Wikipedia [http://en.wikipedia.org/wiki/Sieve_of_Eratosthenes](http://en.wikipedia.org/wiki/Sieve_of_Eratosthenes)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/space-age/README.md b/exercises/space-age/README.md
index 12a08040f3..9d0569a083 100644
--- a/exercises/space-age/README.md
+++ b/exercises/space-age/README.md
@@ -1,5 +1,3 @@
-# Space Age
-
 Given an age in seconds, calculate how old someone would be on:
 
    - Earth: orbital period 365.25 Earth days, or 31557600 seconds
@@ -12,7 +10,8 @@ Given an age in seconds, calculate how old someone would be on:
    - Neptune: orbital period 164.79132 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 Earth-years old.
+be able to say that they're 31.69 Earth-years old. Round all ages to
+the nearest hundredth of a year.
 
 If you're wondering why Pluto didn't make the cut, go watch [this
 youtube video](http://www.youtube.com/watch?v=Z_2gbGXzFbs).
@@ -41,10 +40,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Partially inspired by Chapter 1 in Chris Pine's online Learn to Program tutorial. [http://pine.fm/LearnToProgram/?Chapter=01](http://pine.fm/LearnToProgram/?Chapter=01)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/sum-of-multiples/README.md b/exercises/sum-of-multiples/README.md
index 85ab1f98da..ba5e02fb87 100644
--- a/exercises/sum-of-multiples/README.md
+++ b/exercises/sum-of-multiples/README.md
@@ -1,5 +1,3 @@
-# Sum Of Multiples
-
 Given a number, find the sum of all the multiples of particular numbers up to
 but not including that number.
 
@@ -35,10 +33,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-A variation on Problem 1 at Project Euler [http://projecteuler.net/problem=1](http://projecteuler.net/problem=1)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/tournament/README.md b/exercises/tournament/README.md
index 44ed94c2d4..aaf6ff6ba3 100644
--- a/exercises/tournament/README.md
+++ b/exercises/tournament/README.md
@@ -1,5 +1,3 @@
-# Tournament
-
 Tally the results of a small football competition.
 
 Based on an input file containing which team played against which and what the
@@ -88,7 +86,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/transpose/README.md b/exercises/transpose/README.md
index 5e47bc60f2..53975b63f3 100644
--- a/exercises/transpose/README.md
+++ b/exercises/transpose/README.md
@@ -1,5 +1,3 @@
-# Transpose
-
 Given an input text output it transposed.
 
 Roughly explained, the transpose of a matrix:
@@ -82,10 +80,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Reddit r/dailyprogrammer challenge #270 [Easy]. [https://www.reddit.com/r/dailyprogrammer/comments/4msu2x/challenge_270_easy_transpose_the_input_text](https://www.reddit.com/r/dailyprogrammer/comments/4msu2x/challenge_270_easy_transpose_the_input_text)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/triangle/README.md b/exercises/triangle/README.md
index 6c869777ee..a2e12959b0 100644
--- a/exercises/triangle/README.md
+++ b/exercises/triangle/README.md
@@ -1,5 +1,3 @@
-# Triangle
-
 Determine if a triangle is equilateral, isosceles, or scalene.
 
 An _equilateral_ triangle has all three sides the same length.<br/>
@@ -43,10 +41,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-The Ruby Koans triangle project, parts 1 & 2 [http://rubykoans.com](http://rubykoans.com)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/two-bucket/README.md b/exercises/two-bucket/README.md
index 92c73efa92..35b14cc8c7 100644
--- a/exercises/two-bucket/README.md
+++ b/exercises/two-bucket/README.md
@@ -1,5 +1,3 @@
-# Two Bucket
-
 Given two buckets of different size, demonstrate how to measure an exact number of liters by strategically transferring liters of fluid between the buckets.
 
 Since this mathematical problem is fairly subject to interpretation / individual approach, the tests have been written specifically to expect one overarching solution.
@@ -53,10 +51,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Water Pouring Problem [http://demonstrations.wolfram.com/WaterPouringProblem/](http://demonstrations.wolfram.com/WaterPouringProblem/)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/word-count/README.md b/exercises/word-count/README.md
index 0cbd9d03ea..f724141f79 100644
--- a/exercises/word-count/README.md
+++ b/exercises/word-count/README.md
@@ -1,5 +1,3 @@
-# Word Count
-
 Given a phrase, count the occurrences of each word in that phrase.
 
 For example for the input `"olly olly in come free"`
@@ -36,10 +34,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-This is a classic toy problem, but we were reminded of it by seeing it in the Go Tour.
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/exercises/wordy/README.md b/exercises/wordy/README.md
index 43e43bf534..1fabc3a14c 100644
--- a/exercises/wordy/README.md
+++ b/exercises/wordy/README.md
@@ -1,5 +1,3 @@
-# Wordy
-
 Parse and evaluate simple math word problems returning the answer as an integer.
 
 
@@ -80,10 +78,5 @@ To include color from the command line:
 
     ruby -r minitest/pride hello_world_test.rb
 
-
-## Source
-
-Inspired by one of the generated questions in the Extreme Startup game. [https://github.com/rchatley/extreme_startup](https://github.com/rchatley/extreme_startup)
-
 ## Submitting Incomplete Solutions
 It's possible to submit an incomplete solution so you can see how others have completed the exercise.
diff --git a/lib/generator.rb b/lib/generator.rb
index d14497448f..b17cd98a7c 100644
--- a/lib/generator.rb
+++ b/lib/generator.rb
@@ -4,9 +4,10 @@
 module Generator
   # Immutable value object for storing paths
   class Paths
-    attr_reader :track, :metadata
-    def initialize(track:, metadata:)
+    attr_reader :track, :docs, :metadata
+    def initialize(track:, docs:, metadata:)
       @track = track
+      @docs = docs
       @metadata = metadata
     end
   end
@@ -16,6 +17,7 @@ def initialize(track:, metadata:)
   class GenerateTests < ImplementationDelegator
     def call
       build_tests
+      build_readme
     end
   end
 
@@ -25,6 +27,7 @@ def call
       update_tests_version
       update_example_solution
       build_tests
+      build_readme
     end
   end
 end
diff --git a/lib/generator/exercise.rb b/lib/generator/exercise.rb
index e858a12d1e..6caf6f5542 100644
--- a/lib/generator/exercise.rb
+++ b/lib/generator/exercise.rb
@@ -12,6 +12,14 @@ def name
       @name ||= slug.underscore
     end
 
+    def directory
+      "exercises/#{@slug}"
+    end
+
+    def readme
+      "exercises/#{@slug}/README.md"
+    end
+
     def case_class
       slug.camel_case + 'Case'
     end
diff --git a/lib/generator/files.rb b/lib/generator/files.rb
index 95fff207b4..104c1aff72 100644
--- a/lib/generator/files.rb
+++ b/lib/generator/files.rb
@@ -7,9 +7,10 @@ def self.read(filename)
     end
 
     class Readable
-      attr_reader :filename, :repository_root
-      def initialize(filename:, repository_root: nil)
+      attr_reader :filename, :docs, :repository_root
+      def initialize(filename:, docs: nil, repository_root: nil)
         @filename = filename
+        @docs = docs
         @repository_root = repository_root
       end
 
diff --git a/lib/generator/files/metadata_files.rb b/lib/generator/files/metadata_files.rb
index c68eedf080..10f2ac9c0b 100644
--- a/lib/generator/files/metadata_files.rb
+++ b/lib/generator/files/metadata_files.rb
@@ -4,6 +4,7 @@ module MetadataFiles
       def canonical_data
         CanonicalDataFile.new(
           filename: File.join(metadata_path, 'canonical-data.json'),
+          docs: File.join(metadata_path, 'description.md'),
           repository_root: paths.metadata)
       end
 
diff --git a/lib/generator/implementation.rb b/lib/generator/implementation.rb
index 196c39c957..36d934cd93 100644
--- a/lib/generator/implementation.rb
+++ b/lib/generator/implementation.rb
@@ -33,6 +33,13 @@ def build_tests
         values: template_values
       )
     end
+
+    def build_readme
+      canonicalDocs = File.read(@repository.canonical_data().docs)
+      rubyDocs = File.read(@repository.paths.docs)
+      readme = File.join(@repository.paths.track, @exercise.readme)
+      File.open(readme, "w") { |handle| handle.puts "#{canonicalDocs}\n#{rubyDocs}" }
+    end
   end
 
   # This exists to give us a clue as to what we are delegating to.
@@ -60,5 +67,10 @@ def build_tests
       @implementation.build_tests
       @logger.info "Generated #{exercise.slug} tests version #{version}"
     end
+
+    def build_readme
+      @implementation.build_readme
+      @logger.info "Generated #{exercise.slug} README"
+    end
   end
 end
diff --git a/lib/helper.rb b/lib/helper.rb
index bb1874b49e..ee7a4b2b98 100644
--- a/lib/helper.rb
+++ b/lib/helper.rb
@@ -1,5 +1,6 @@
 EXERCISM_RUBY_ROOT = File.join(File.dirname(__FILE__), '..').freeze
 EXERCISM_RUBY_LIB = File.join(EXERCISM_RUBY_ROOT, 'lib').freeze
+EXERCISM_RUBY_DOCS = File.join(EXERCISM_RUBY_ROOT, 'docs/EXERCISE_README_INSERT.md').freeze
 METADATA_REPOSITORY_PATH = File.join(EXERCISM_RUBY_ROOT, '..', 'problem-specifications').freeze
 
 $LOAD_PATH.unshift(EXERCISM_RUBY_LIB)
diff --git a/test/fixtures/docs/EXERCISE_README_INSERT.md b/test/fixtures/docs/EXERCISE_README_INSERT.md
new file mode 100644
index 0000000000..bcce0b9f76
--- /dev/null
+++ b/test/fixtures/docs/EXERCISE_README_INSERT.md
@@ -0,0 +1,2 @@
+****
+Ruby instructions on how to run tests.
\ No newline at end of file
diff --git a/test/fixtures/metadata/exercises/alpha/description.md b/test/fixtures/metadata/exercises/alpha/description.md
new file mode 100644
index 0000000000..dbeab99431
--- /dev/null
+++ b/test/fixtures/metadata/exercises/alpha/description.md
@@ -0,0 +1,5 @@
+Add two numbers together
+
+## Requirements
+
+* The numbers should be added together
diff --git a/test/generator/command_line/generator_optparser_test.rb b/test/generator/command_line/generator_optparser_test.rb
index 8375c69857..385a542d5a 100644
--- a/test/generator/command_line/generator_optparser_test.rb
+++ b/test/generator/command_line/generator_optparser_test.rb
@@ -4,6 +4,7 @@ module Generator
   class GeneratorOptparserTest < Minitest::Test
     FixturePaths = Paths.new(
       metadata: 'test/fixtures/metadata',
+      docs: 'test/fixtures/metadata',
       track: 'test/fixtures/ruby'
     )
 
@@ -87,7 +88,7 @@ def test_usage_help_includes_available_generators
     end
 
     def test_invalid_metadata_repository_outputs_message_to_stderr
-      paths = Paths.new(metadata: 'test/fixtures/nonexistent', track: nil)
+      paths = Paths.new(metadata: 'test/fixtures/nonexistent', track: nil, docs: nil)
       expected_stderr = <<-MESSAGE.gsub(/^ {6}/, '')
       'problem-specifications' repository not found.
       Try running the command:
diff --git a/test/generator/command_line_test.rb b/test/generator/command_line_test.rb
index a4a7aec2d0..c6fc0daaec 100644
--- a/test/generator/command_line_test.rb
+++ b/test/generator/command_line_test.rb
@@ -4,6 +4,7 @@ module Generator
   class CommandLineTest < Minitest::Test
     FixturePaths = Paths.new(
       metadata: 'test/fixtures/metadata',
+      docs: 'test/fixtures/metadata',
       track: 'test/fixtures/ruby'
     )
 
@@ -15,7 +16,7 @@ def test_parse
     end
 
     def test_invalid_metadata_repository_outputs_message_to_stderr
-      paths = Paths.new(metadata: 'test/fixtures/nonexistent', track: nil)
+      paths = Paths.new(metadata: 'test/fixtures/nonexistent', track: nil, docs: nil)
       expected_stderr = <<-MESSAGE.gsub(/^ {6}/, '')
       'problem-specifications' repository not found.
       Try running the command:
diff --git a/test/generator/files/metadata_files_test.rb b/test/generator/files/metadata_files_test.rb
index 5b80e8c092..3f1eac5c21 100644
--- a/test/generator/files/metadata_files_test.rb
+++ b/test/generator/files/metadata_files_test.rb
@@ -4,6 +4,7 @@ module Files
     class MetadataFilesTest < Minitest::Test
       FixturePaths = Paths.new(
         metadata: 'test/fixtures/metadata',
+        docs: 'test/fixtures/metadata',
         track: 'test/fixtures/ruby'
       )
 
diff --git a/test/generator/files/track_files_test.rb b/test/generator/files/track_files_test.rb
index 24d7a39dd4..1203d496e2 100644
--- a/test/generator/files/track_files_test.rb
+++ b/test/generator/files/track_files_test.rb
@@ -5,6 +5,7 @@ module Files
     class TrackFilesTest < Minitest::Test
       FixturePaths = Paths.new(
         metadata: 'test/fixtures/metadata',
+        docs: 'test/fixtures/metadata',
         track: 'test/fixtures/ruby'
       )
 
diff --git a/test/generator/implementation_test.rb b/test/generator/implementation_test.rb
index 12009af043..478e26262a 100644
--- a/test/generator/implementation_test.rb
+++ b/test/generator/implementation_test.rb
@@ -4,6 +4,7 @@ module Generator
   class ImplementationTest < Minitest::Test
     FixturePaths = Paths.new(
       metadata: 'test/fixtures/metadata',
+      docs: 'test/fixtures/docs/EXERCISE_README_INSERT.md',
       track: 'test/fixtures/ruby'
     )
 
@@ -96,6 +97,16 @@ def test_bookkeeping
       # Don't pollute the namespace
       Object.send(:remove_const, :AlphaCase)
     end
+
+    def test_build_readme
+      expected_content = "Add two numbers together\n\n## Requirements\n\n* The numbers should be added together\n\n****\nRuby instructions on how to run tests."
+      mock_file = Minitest::Mock.new.expect :puts, expected_content.length, [expected_content]
+      exercise = Exercise.new(slug: 'alpha')
+      repository = Repository.new(paths: FixturePaths, slug: 'alpha')
+      subject = Implementation.new(repository: repository, exercise: exercise)
+      File.stub(:open, true, mock_file) { subject.build_readme }
+      mock_file.verify
+    end
   end
 
   class LoggingImplementationTest < Minitest::Test
@@ -114,6 +125,20 @@ def test_build_tests
       mock_implementation.verify
     end
 
+    def test_build_readme
+      exercise = Exercise.new(slug: 'alpha')
+      mock_implementation = Minitest::Mock.new
+      mock_implementation.expect :build_readme, nil
+      mock_implementation.expect :exercise, exercise
+      mock_logger = Minitest::Mock.new
+      mock_logger.expect :info, nil, ['Generated alpha README']
+
+      subject = LoggingImplementation.new(implementation: mock_implementation, logger: mock_logger)
+      subject.build_readme
+
+      mock_implementation.verify
+    end
+
     def test_update_tests_version
       mock_implementation = Minitest::Mock.new
       mock_implementation.expect :update_tests_version, nil
diff --git a/test/generator_test.rb b/test/generator_test.rb
index b376960afa..db4ab160d0 100644
--- a/test/generator_test.rb
+++ b/test/generator_test.rb
@@ -7,6 +7,7 @@ def test_call
       mock_exercise.expect :update_tests_version, nil
       mock_exercise.expect :update_example_solution, nil
       mock_exercise.expect :build_tests, nil
+      mock_exercise.expect :build_readme, nil
 
       subject = UpdateVersionAndGenerateTests.new(mock_exercise)
       subject.call
@@ -19,6 +20,7 @@ class UpdateVersionAndGenerateTestsFrozenVersionTest < Minitest::Test
     def test_call
       mock_exercise = Minitest::Mock.new
       mock_exercise.expect :build_tests, nil
+      mock_exercise.expect :build_readme, nil
 
       subject = GenerateTests.new(mock_exercise)
       subject.call