diff --git a/docs/Dispatch.md b/docs/Dispatch.md
index 543fced54..abc149f99 100644
--- a/docs/Dispatch.md
+++ b/docs/Dispatch.md
@@ -1,44 +1,44 @@
 # Dispatch architecture
 ```
-                          Message from
-                          client
- +                             +                                +
- |                             |                                |
- |                       +-----v-----+                          |
- |                       |           |                          |
- <-------+IdeRequest<----+  Reactor  +------->GhcRequest+------->
- |                       |           |                          |
- |                       +-----------+                          |
- |                                                              |
- |                                                              |
-IdeM                                                         IdeGhcM      +--------+
- |             +----->IdeResponseDeferred                       |         |        |
- |             |                   +                            +--------->        |
- |             |                   |                            |         |  ghc   |
- |             +                   |                            |         |  mod   |
- +------->IdeResponse              |    Triggers<----+          <---------+        |
- |            +    ^               |       |         |          |         |        |
- |            |    |           +---v-------v--+      |          |         |        |
- |            |    |           |              |      +          |         +--------+
- |            |    +-----------+ RequestQueue |  cacheModule<---+
- |            |                |              |                 |
- |            |                +--------------+                 |
- |            |                                                 |
- |            |  +----------------------------------------------+
- |            v  v                                              |
- |         IdeResult                                            |
- |          +    +                                              |
- |          v    |                                              |
- | IdeResultFail |                                              |
- |               v                                              |
- |          IdeResultOk                                         |
- |               +                                              |
- |               v                                              |
- |          RequestCallback                                     |
- v               +                                              v
-                 v
-          Possibly respond to
-          client if needed
+                                    Message from
+                                    client
+            +                             +                                +
+            |                             |                                |
+            |                       +-----v-----+                          |
+            |                       |           |                          |
+            <-------+IdeRequest<----+  Reactor  +------->GhcRequest+------->
+            |                       |           |                          |
+            |                       +-----------+                          |
+            |                                                              |
+            |                                                              |
+           IdeM                                                         IdeGhcM      +--------+
+            |             +----->IdeResponseDeferred                       |         |        |
+ plugins <--+             |                   +                            +--------->        |
+    |       |             |                   |                            |         |  ghc   |
+    +------->             +                   |                            |         |  mod   |
+            +------->IdeResponse              |    Triggers<----+          <---------+        |
+            |            +    ^               |       |         |          |         |        |
+            |            |    |           +---v-------v--+      |          |         |        |
+            |            |    |           |              |      +          |         +--------+
+            |            |    +-----------+ RequestQueue |  cacheModule<---+
+            |            |                |              |                 |
+            |            |                +--------------+                 |
+            |            |                                                 |
+            |            |  +----------------------------------------------+
+            |            v  v                                              |
+            |         IdeResult                                            |
+            |          +    +                                              |
+            |          v    |                                              |
+            | IdeResultFail |                                              |
+            |               v                                              |
+            |          IdeResultOk                                         |
+            |               +                                              |
+            |               v                                              |
+            |          RequestCallback                                     |
+            v               +                                              v
+                            v
+                    Possibly respond to
+                    client if needed
 ```
 
 ## Reactor
@@ -55,6 +55,10 @@ The 2 threads are represented by 2 monads: `IdeM` and `IdeGhcM`.
 to ghc-mod, since `IdeGhcM` is used mainly for typechecking modules and is
 the most constrained resource.
 
+## Requests
+To get onto the threads, send an `IReq` or `GReq` to the dispatcher with
+`makeRequest` inside `LspStdio.hs:reactor`.
+
 ## Responses
 If you are on `IdeM` and need access to a cached module, consider using an
 `IdeResponseDeferred`. You can provide it with a `FilePath` to a module you
@@ -67,4 +71,4 @@ helper functions instead.
 ## Results
 An `IdeResponse` will eventually return an `IdeResult` at the end of the day,
 which will hand back data to the Reactor. `IdeGhcM` skips the response part
-and returns an `IdeResult` directly since it will never need to be deferred.
+and returns an `IdeResult` directly since it will never need to be deferred.
\ No newline at end of file
diff --git a/docs/Hacking.md b/docs/Hacking.md
index cf0d4a9d7..76ae6d0cb 100644
--- a/docs/Hacking.md
+++ b/docs/Hacking.md
@@ -5,6 +5,7 @@
 ```
 $ git clone https://github.com/haskell/haskell-ide-engine.git
 $ cd haskell-ide-engine
+$ git submodule update --init
 $ stack build
 ```
 
diff --git a/docs/Packages.md b/docs/Packages.md
new file mode 100644
index 000000000..ac0e2e399
--- /dev/null
+++ b/docs/Packages.md
@@ -0,0 +1,55 @@
+# Packages
+
+```
++----------------------------+
+|                            |
+|     haskell-ide-engine     |
+|                            |
+| +------------------------+ |    +------------------+
+| |                        | |    |                  |
+| | haskell-ide-engine-api | +----> haskell-lsp-test |
+| |                        | |    |                  |
+| +------------------------+ |    +-+----------------+
+|                            |      |
++--------------------+-------+      |
+                     |              |
+                     |              |
+                +----v--------------v---+
+                |                       |
+                |      haskell-lsp      |
+                |                       |
+                | +-------------------+ |
+                | |                   | |
+                | | haskell-lsp-types | |
+                | |                   | |
+                | +-------------------+ |
+                |                       |
+                +-----------------------+
+
+```
+
+HIE is built upon various separate repositories and packages:
+
+## [haskell-lsp](https://github.com/alanz/haskell-lsp)
+Provides core functions for running a LSP server:
+- Sending messages
+- Parsing and receiving messages to various handlers
+- Mirroring client documents in a virtual file system (VFS)
+
+### haskell-lsp-types
+A separate package within haskell-lsp that provides all the types as described in the specification.
+Includes lenses and some helper functions for converting between types.
+The separate package prevents unnecessary rebuilds of the template haskell files (which can take a long time) when working on haskell-ide-engine or haskell-lsp.
+
+## [haskell-ide-engine](https://github.com/haskell/haskell-ide-engine)
+An executable server that routes LSP requests to various tools in the haskell ecosystem.
+Builds on top of haskell-lsp.
+Uses plugins to connect the tools into the server.
+Add plugin functionality in the `plugins` directory, and then hook it up to an appropriate LSP feature in `LspStdio.hs`.
+
+### hie-plugin-api
+Types, monads and functions for the plugins in `haskell-ide-engine`.
+
+## haskell-lsp-test
+A testing framework for LSP servers where scenarios can be captured or described in terms of messages.
+Used by HIE for functional tests. 
\ No newline at end of file