tidy up README.md's

3 files changed, 34 insertions, 7 deletions

diff --git a/lib/sampling/README.md b/lib/sampling/README.md
index 28c603e..731f1d1 100644
--- a/lib/sampling/README.md
+++ b/lib/sampling/README.md
@@ -1,28 +1,41 @@
-Files in this directory should be modules implementing the following
+Sampling interface
+==================
+
+Files in this directory should be _modules_ implementing the following
 interface:
 
  - `works_with?(Game) => Boolean`
+
    Returns whether or not this sampling method works with the
    specified game.
 
  - `uses_remote?() => Boolean`
+
    Return whether or not this sampling method requires remote IDs for
    users.
  - `set_remote_name(User, Game, String)`
+
    Set the remote ID for a user for the specified game.  It is safe to
    assume that this sampling method `works_with?` that game.
  - `get_remote_name(Object)`
+
    When given an object from `RemoteUsername#value`, give back a
    human-readable/editable name to display.
 
  - `sampling_start(Match)`
+
    Fetch the statistics for a match.
+
  - `sampling_done?(Match) => Boolean`
+
    Returns whether or not statistics have been completely collected
    yet.
 
  - `render_user_interaction(Match, User) => String`
+
    Returns HTML to render on a page.
+
  - `handle_user_interaction(Match, User, Hash params)`
+
    Handles params from the form generated by
    `#user_interaction_render`.
diff --git a/lib/scheduling/README.md b/lib/scheduling/README.md
index 173b7be..8b21164 100644
--- a/lib/scheduling/README.md
+++ b/lib/scheduling/README.md
@@ -1,13 +1,22 @@
-Files in this directory should implement the following interface:
+Scheduling interface
+====================
+
+Files in this directory should be _classes_ implementing the following
+interface:
 
  - `initialize(tournament_stage)`
-	construct new Scheduling object from tournament_stage
+
+   Construct new Scheduling object from tournament_stage.
 
  - `create_matches`
- 	creates all the matches of the current round
+
+   Creates all the matches of the current round.
 
  - `finish_match(match)`
- 	progresses the match through the schedule
+
+   Progresses the match through the schedule.
 
  - `graph`
- 	returns a string representation of an svg image of the current stage
\ No newline at end of file
+
+   Returns a string representation of an svg image of the current
+   stage.
diff --git a/lib/scoring/README.md b/lib/scoring/README.md
index 95dd5e0..5beb0a2 100644
--- a/lib/scoring/README.md
+++ b/lib/scoring/README.md
@@ -1,10 +1,15 @@
-Files in this directory should be modules implementing the following
+Scoring interface
+=================
+
+Files in this directory should be _modules_ implementing the following
 interface:
 
  - `stats_needed() => Array[i]=Symbol`
+
    Returns which statistics need to be collected for this scoring
    algorithm.
 
  - `score(match) => Hash[User]=Integer`
+
    User scores for this match, assuming statistics have been
    collected.