README updates (#856)

* README: Remove mentions of master branch

* README: Add instructions for using html-test

* README: Change command to run _all_ the testsuites

* README: Add project overview section

(cherry picked from commit 61d6f935da97eb96685f07bf385102c2dbc2a33c)

1 files changed, 36 insertions, 5 deletions

diff --git a/README.md b/README.md
index bfc2261b..51642aab 100644
--- a/README.md
+++ b/README.md
@@ -11,6 +11,32 @@ Full documentation can be found in the `doc/` subdirectory, in
 [reStructedText format](http://www.sphinx-doc.org/en/stable/rest.html)
 format.
 
+
+## Project overview
+
+This project consists of three packages:
+
+* haddock
+* haddock-api
+* haddock-library
+
+### haddock
+
+The haddock package provides the `haddock` executable. It is implemented as a
+tiny wrapper around haddock-api's `Documentation.Haddock.haddock` function.
+
+### haddock-api
+
+haddock-api contains the program logic of the `haddock` tool. [The haddocks for
+the `Documentation.Haddock` module](http://hackage.haskell.org/package/haddock-api-2.19.0.1/docs/Documentation-Haddock.html)
+offer a good overview of haddock-api's functionality.
+
+### haddock-library
+
+haddock-library is concerned with the parsing and processing of the Haddock
+markup language.
+
+
 ## Contributing
 
 Please create issues when you have any problems and pull requests if you have some code.
@@ -33,7 +59,7 @@ and then proceed using your favourite build tool.
 ```bash
 cabal new-build -w ghc-8.4.1
 # build & run the test suite
-cabal new-test -w ghc-8.4.1
+cabal new-test -w ghc-8.4.1 all
 ```
 
 #### Using Cabal sandboxes
@@ -65,11 +91,16 @@ stack test
 ### Git Branches
 
 If you're a GHC developer and want to update Haddock to work with your
-changes, you should be working on `ghc-head` branch instead of `master`.
+changes, you should be working on `ghc-head` branch.
 See instructions at
 https://ghc.haskell.org/trac/ghc/wiki/WorkingConventions/Git/Submodules
 for an example workflow.
 
-The `master` branch usually requires a GHC from the latest GHC stable
-branch. The required GHC version can be inferred from the version
-bounds on `ghc` in the respective `.cabal` files.
+### Updating `html-test`
+
+When accepting any changes in the output of `html-test`, it is important
+to use the `--haddock-path` option. For example:
+
+```
+cabal new-run -- html-test --haddock-path $(find dist-newstyle/ -executable -type f -name haddock) --accept
+```