diff --git a/bin/clean_html b/bin/clean_html
index 9e3e9c84c..8f0ec83d9 100755
--- a/bin/clean_html
+++ b/bin/clean_html
@@ -1,7 +1,7 @@
 #!/bin/bash
 
-# This script finds all .t2t (txt2tags) and .md (markdown) files
-# and deletes the corresponding html file
+# This script finds all .t2t (txt2tags) and .md (Markdown) files
+# and deletes the corresponding HTML file of the same name.
 
 find . -name '*.t2t' | while read t2t ; do
   html="${t2t%.t2t}.html"
diff --git a/bin/update_html b/bin/update_html
index 8e96139ca..e6e8877de 100755
--- a/bin/update_html
+++ b/bin/update_html
@@ -1,5 +1,22 @@
 #!/bin/bash
 
+# Generate HTML from txt2tags (.t2t) and Markdown (.md)
+# Usage:
+# - update_html
+#   Look for all .t2t and .md files in the current directory and below,
+#   generating the output HTML when the source is newer than the HTML.
+# - update_html path/to/file.t2t path/to/another.md
+#   Generate HTML for the specified file(s), ignoring modification time.
+#
+# Requires:
+# - txt2tags for .t2t files. Tested with 2.6.
+# - pandoc for both .t2t and .md files. Tested with 1.16.0.2 and 2.3.1.
+# - the template file `template.html` in the same directory as this script.
+#
+# Tested with Ubuntu 16.04 and macOS Mojave.
+#
+# See also clean_html for removing the files generated by this script.
+
 # Path to directory where this script is
 # https://stackoverflow.com/a/246128/98600
 DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" >/dev/null && pwd )"