diff --git a/bin/README b/bin/README
index 82d4af69a..c0ebd75eb 100644
--- a/bin/README
+++ b/bin/README
@@ -1,13 +1,23 @@
 hledger add-on commands, hledger-related scripts, developer builds.
 
-Scripts named hledger-* are hledger add-on commands. You can run them directly,
-or via "hledger [HLEDGEROPTS] ADDONCMD [-- ADDONOPTS]". You should:
-1. add this directory to your $PATH
-2. ensure the scripts have executable permission (they should already, at least on unix)
-3. optionally, compile them for quicker startup
-See also: http://hledger.org/hledger.html#add-on-commands
+Scripts named hledger-* are hledger add-on commands. The ones in this
+bin/ directory are tested along with hledger, but shipped as add-ons
+rather than built-in commands because they are experimental, or
+for some other reason.
 
-Other hledger-related scripts include bash aliases, makefile examples, etc.
+Add this directory to your $PATH and they will show up as commands
+listed by hledger (or, you can run them directly).
+To speed them up (recommended), compile them:
 
-hledger development-related binaries also are stored here, such as
-old versions for benchmarking, and platform-specific binaries.
+$ bin/compile.sh
+
+When using hledger to run add-on commands, remember to use a --
+before add-on-specific options or hledger will complain. Like so:
+
+$ hledger [HLEDGEROPTS] ADDONCMD [-- ADDONOPTS]
+
+See also http://hledger.org/hledger.html#add-on-commands .
+
+hledger-related bash scripts, example make rules etc. are also kept here.
+And hledger developer binaries may get stored here,
+such as old versions for benchmarking, and platform-specific binaries.
diff --git a/bin/compile.sh b/bin/compile.sh
new file mode 100755
index 000000000..c1729b5cf
--- /dev/null
+++ b/bin/compile.sh
@@ -0,0 +1,8 @@
+#!/bin/sh
+cd "$(dirname "$0")"
+echo "building dependencies"
+stack build hledger
+echo "building add-on commands"
+for f in hledger-*.hs; do stack ghc $f; done
+echo "add-on commands available:"
+ls -F hledger-* | grep -vE '\.(hs|hi|o)'
diff --git a/bin/hledger-check-dates.hs b/bin/hledger-check-dates.hs
index f2cac0970..c53396358 100755
--- a/bin/hledger-check-dates.hs
+++ b/bin/hledger-check-dates.hs
@@ -3,15 +3,16 @@
    --package hledger-lib
    --package hledger
 -}
--- You can compile this script for speed:
--- stack build hledger && stack ghc bin/hledger-check-dates.hs
+{-
 
-{-|
 hledger-check-dates [--strict] [--date2] [-f JOURNALFILE]
 
 Check that transactions' date are monotonically increasing.
-Reads the default or specified journal.
-|-}
+With --strict, dates must also be unique.
+With --date2, checks transactions' secondary dates.
+Reads the default journal file, or another specified with -f.
+
+-}
 
 import Hledger
 import Hledger.Cli
diff --git a/bin/hledger-equity.hs b/bin/hledger-equity.hs
index cd0dccab2..9ad0835f2 100755
--- a/bin/hledger-equity.hs
+++ b/bin/hledger-equity.hs
@@ -4,10 +4,8 @@
    --package hledger
    --package time
 -}
--- You can compile this script for speed:
--- stack build hledger && stack ghc bin/hledger-equity.hs
-
 {-
+
 hledger-equity [HLEDGEROPTS] [QUERY]
 
 Show a "closing balances" transaction that brings the balance of the
diff --git a/bin/hledger-print-unique.hs b/bin/hledger-print-unique.hs
index 7e6e6f10c..20de1d394 100755
--- a/bin/hledger-print-unique.hs
+++ b/bin/hledger-print-unique.hs
@@ -3,10 +3,8 @@
    --package hledger-lib
    --package hledger
 -}
--- You can compile this script for speed:
--- stack build hledger && stack ghc bin/hledger-print-unique.hs
-
 {-
+
 hledger-print-unique [-f JOURNALFILE | -f-]
 
 Print only journal entries which are unique by description (or
diff --git a/bin/hledger-register-match.hs b/bin/hledger-register-match.hs
index cab5b016d..44ef03834 100755
--- a/bin/hledger-register-match.hs
+++ b/bin/hledger-register-match.hs
@@ -4,10 +4,8 @@
    --package hledger
    --package text
 -}
--- You can compile this script for speed:
--- stack build hledger && stack ghc bin/hledger-register-match.hs
+{-
 
-{-|
 hledger-register-match DESC
 
 A helper for ledger-autosync. This prints the one posting whose transaction
@@ -15,7 +13,7 @@ description is closest to DESC, in the style of the register command.
 If there are multiple equally good matches, it shows the most recent.
 Query options (options, not arguments) can be used to restrict the search space.
 
-|-}
+-}
 
 {-# LANGUAGE OverloadedStrings #-}
 
diff --git a/bin/hledger-rewrite.hs b/bin/hledger-rewrite.hs
index 43c5f7380..325a9b506 100755
--- a/bin/hledger-rewrite.hs
+++ b/bin/hledger-rewrite.hs
@@ -5,10 +5,8 @@
   --package megaparsec
   --package text
 -}
--- You can compile this script for speed:
--- stack build hledger && stack ghc bin/hledger-rewrite.hs
+{-
 
-{-|
 hledger-rewrite [PATTERNS] --add-posting "ACCT  AMTEXPR" ...
 
 A start at a generic rewriter of journal entries.
@@ -32,7 +30,7 @@ TODO:
 - should apply the rule for each matched posting within a transaction, if there's more than one
 - should be possible to use this on unbalanced entries, eg while editing one
 
-|-}
+-}
 
 import qualified Data.Text as T
 -- hledger lib, cli and cmdargs utils