Add section on golden files to test/README.md

test/README.md

@@ -13,3 +13,18 @@ For example, the testsuite can be invoked with:
 ```console
 HPC=hpc GHC=ghc cabal test
 ```
+
+## Managing the golden files
+
+The tests in the `test/Markup` directory, are comparing the HTML output produced by `hpc markup` with the golden files stored in `test/Markup/golden`.
+
+Call to update the golden files:
+```
+make update-golden
+```
+
+To compare an output file to a golden file while simultaneously pretty-printing both:
+
+```
+diff <(tidy -quiet test/Markup/gold/Recip/hpc_index.html) <(tidy -quiet test/Markup/input/Recip/hpc_index.html)
+```