diff --git a/README.md b/README.md
index b14373d..4f213d6 100644
--- a/README.md
+++ b/README.md
@@ -8,9 +8,101 @@
 [![License](https://img.shields.io/packagist/l/felixfbecker/language-server.svg)](https://github.com/felixfbecker/php-language-server/blob/master/LICENSE.txt)
 [![Gitter](https://badges.gitter.im/felixfbecker/php-language-server.svg)](https://gitter.im/felixfbecker/php-language-server?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge)
 
-A pure PHP implementation of the [Language Server Protocol](https://github.com/Microsoft/language-server-protocol).
+A pure PHP implementation of the open [Language Server Protocol](https://github.com/Microsoft/language-server-protocol).
+Provides static code analysis for PHP for any IDE.
 
-![Find all symbols demo](images/documentSymbol.gif)
+Uses the great [PHP-Parser](https://github.com/nikic/PHP-Parser),
+[phpDocumentor's DocBlock reflection](https://github.com/phpDocumentor/ReflectionDocBlock)
+and an [event loop](http://sabre.io/event/loop/) for concurrency.
+
+## Features
+
+### [Go To Definition](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#goto-definition-request)
+![Go To Definition demo](images/definition.gif)
+
+### [Find References](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#find-references-request)
+![Find References demo](images/references.png)
+
+### [Hover](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#hover-request)
+![Hover class demo](images/hoverClass.png)
+
+![Hover parameter demo](images/hoverParam.png)
+
+A hover request returns a declaration line (marked with language `php`) and the summary of the docblock.
+For Parameters, it will return the `@param` tag.
+
+### [Document Symbols](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#document-symbols-request)
+![Document Symbols demo](images/documentSymbol.gif)
+
+### [Workspace Symbols](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#workspace-symbols-request)
+![Workspace Symbols demo](images/workspaceSymbol.gif)
+
+The query is matched case-insensitively against the fully qualified name of the symbol.  
+Non-Standard: An empty query will return _all_ symbols found in the workspace.
+
+### [Document Formatting](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#document-formatting-request)
+![Document Formatting demo](images/formatDocument.gif)
+
+### Error reporting through [Publish Diagnostics](https://github.com/Microsoft/language-server-protocol/blob/master/protocol.md#publishdiagnostics-notification)
+![Error reporting demo](images/publishDiagnostics.png)
+
+PHP parse errors are reported as errors, parse errors of docblocks are reported as warnings.
+
+### What is considered a definition?
+
+Globally searchable definitions are:
+ - classes
+ - interfaces
+ - traits
+ - properties
+ - methods
+ - class constants
+ - constants with `const` keyword
+
+Definitions resolved just-in-time when needed:
+ - variable assignments
+ - parameters
+ - closure `use` statements
+
+Not supported yet:
+ - constants with `define()`
+
+Namespaces are not considerd a declaration by design because they only make up a part of the fully qualified name
+and don't map to one unique declaration.
+
+### What is considered a reference?
+
+Definitions/references/hover currently work for
+ - class instantiations
+ - static method calls
+ - class constant access
+ - static property access
+ - parameter type hints
+ - return type hints
+ - method calls, if the variable was assigned to a new object in the same scope
+ - property access, if the variable was assigned to a new object in the same scope
+ - variables
+ - parameters
+ - imported closure variables (`use`)
+ - `use` statements for classes, constants and functions
+ - class-like after `implements`/`extends`
+ - function calls
+ - constant access
+ - `instanceof` checks
+
+They do not work yet for:
+ - Reassigned variables
+ - Nested access/calls on return values or properties
+
+## Performance
+
+Upon initialization, the server will recursively scan the project directory for PHP files, parse them and add all definitions
+and references to an in-memory index.
+The time this takes depends on the project size.
+At the time of writing, this project contains 78 files + 1560 files in dependencies which take 97s to parse
+and consume 76 MB on a Surface Pro 3.
+The language server is fully operational while indexing and can respond to requests with the definitions already indexed.
+Follow-up requests will be almost instant because the index is kept in memory.
 
 ## Used by
  - [vscode-php-intellisense](https://github.com/felixfbecker/vscode-php-intellisense)
@@ -26,20 +118,27 @@ to install dependencies.
 
 Run the tests with 
 
-    vendor/bin/phpunit --bootstrap vendor/autoload.php tests
+    vendor/bin/phpunit
+
+Lint with
+
+    vendor/bin/phpcs
 
 ## Command line arguments
 
-###### --tcp=host:port (optional)
+### `--tcp=host:port` (optional)
 Causes the server to use a tcp connection for communicating with the language client instead of using STDIN/STDOUT.
 The server will try to connect to the specified address.
+Strongly recommended on Windows because of blocking STDIO.
 
 Example:
 
     php bin/php-language-server.php --tcp=127.0.0.1:12345
 
-###### --memory-limit=integer (optional)
-Sets memory limit for language server. Equivalent to [memory-limit](http://php.net/manual/en/ini.core.php#ini.memory-limit) *php.ini* directive. By default there is no memory limit.
+### `--memory-limit=integer` (optional)
+Sets memory limit for language server.
+Equivalent to [memory-limit](http://php.net/manual/en/ini.core.php#ini.memory-limit) php.ini directive.
+By default there is no memory limit.
 
 Example:
 
diff --git a/images/definition.gif b/images/definition.gif
new file mode 100644
index 0000000..f283b3c
Binary files /dev/null and b/images/definition.gif differ
diff --git a/images/formatDocument.gif b/images/formatDocument.gif
new file mode 100644
index 0000000..d8e49fe
Binary files /dev/null and b/images/formatDocument.gif differ
diff --git a/images/hoverClass.png b/images/hoverClass.png
new file mode 100644
index 0000000..29dfcc3
Binary files /dev/null and b/images/hoverClass.png differ
diff --git a/images/hoverParam.png b/images/hoverParam.png
new file mode 100644
index 0000000..26171a9
Binary files /dev/null and b/images/hoverParam.png differ
diff --git a/images/publishDiagnostics.png b/images/publishDiagnostics.png
new file mode 100644
index 0000000..4499b70
Binary files /dev/null and b/images/publishDiagnostics.png differ
diff --git a/images/references.png b/images/references.png
new file mode 100644
index 0000000..15e50ea
Binary files /dev/null and b/images/references.png differ
diff --git a/images/workspaceSymbol.gif b/images/workspaceSymbol.gif
new file mode 100644
index 0000000..a3f0fca
Binary files /dev/null and b/images/workspaceSymbol.gif differ