Add description of Psalm‘s features

README.md

@@ -5,12 +5,11 @@
 [![Travis CI](https://img.shields.io/travis/vimeo/psalm/master.svg)](https://travis-ci.org/vimeo/psalm/branches)
 [![Coverage Status](https://coveralls.io/repos/github/vimeo/psalm/badge.svg)](https://coveralls.io/github/vimeo/psalm)
 
-Psalm is a static analysis tool for finding errors in PHP applications.
+Psalm is a static analysis tool for finding errors in PHP applications, built on top of [PHP Parser](https://github.com/nikic/php-parser).
 
- - **v0.3.x** supports checking PHP 5.4 - 7.1 code, and requires **PHP 5.6+** to run.
- - **v0.2.x** supports checking PHP 5.4 - 7.0 code and requires **PHP 5.4+** to run.
+It's able to find a [large number issues](https://github.com/vimeo/psalm/blob/master/docs/issues.md), but it can also be configured to only care about a small subset of those.
 
-Check out the [wiki](https://github.com/vimeo/psalm/wiki) or [try a live demo](https://getpsalm.org/)!
+[Read more about Psalm](https://github.com/vimeo/psalm/blob/master/docs/index.md), [try a live demo](https://getpsalm.org/), or install it in your project by following the guide below.
 
 ## Quickstart Guide
 
@@ -38,7 +37,7 @@ The config created above will show you all issues in your code, but will emit `I
 ./vendor/bin/psalm --init [source_dir] [level]
 ```
 
-You can also [learn how to suppress certain issues](https://github.com/vimeo/psalm/wiki/Dealing-with-code-issues).
+You can also [learn how to suppress certain issues](https://github.com/vimeo/psalm/blob/master/docs/dealing_with_code_issues.md).
 
 ## How Psalm Works
 
@@ -47,5 +46,3 @@ A basic rundown of Psalm’s internals can be found in [docs/how_psalm_works.md]
 ## Acknowledgements
 
 The engineering team [@vimeo](https://github.com/vimeo) for encouragement and patience, especially [@nbeliard](https://github.com/nbeliard), [@erunion](https://github.com/erunion) and [@nickyr](https://github.com/nickyr).
-
-Thanks also to [@nikic](https://github.com/nikic) for creating the excellent [php-parser](https://github.com/nikic/php-parser), on top of which Psalm is built.

docs/index.md

@@ -2,4 +2,57 @@
 
 <abbr title="PHP Static Analysis Linting Machine">Psalm</abbr> is a static analysis tool that attempts to dig into your program and find as many type-related bugs as possible.
 
-The end goal of Psalm is not just to find bugs, but to have an understand your code so that you don't have to.
+- [Introduction](#introduction)
+- [Installation](installation.md)
+- [Configuration](configuration.md)
+- [Running Psalm](running_psalm.md)
+- [Dealing with code issues](dealing_with_code_issues.md)
+- [Typing in Psalm](typing_in_psalm.md)
+- [Plugins](plugins.md)
+- [Checking non-PHP files](checking_non_php_files.md)
+
+## Introduction
+
+Psalm tries to understand your codebase as best as possible so it can find errors.
+
+It has a few features that go further than other similar tools:
+
+- **Mixed type warnings**<br />
+  If Psalm cannot infer a type for an expression then it uses a `mixed` placeholder. Any `mixed` type is a sign of an insufficiently-documented codebase. You can configure Psalm warn when encountering `mixed` types by adding *`totallyTyped="true"`* attribute to your XML config file.
+
+- **Logic checks**<br />
+  Psalm keeps track of logical assertions made about your code, so `if ($a && $a) {}` and `if ($a && !$a) {}` are both treated as issues. Psalm also keeps track of logical assertions made in prior code paths, preventing issues like `if ($a) {} elseif ($a) {}`.
+
+- **Property initialisation checks**<br />
+  Psalm checks that all properties of a given object have values after the constructor is called.
+
+- **Support for complicated array shapes**<br />
+  Psalm has support for [object-like arrays](supported_annotations.md#object-like-arrays), allowing you to specify types for all keys of an array if you so wish.
+
+Psalm also has a few features to make it perform as well as possible on large codebases:
+
+- **Multi-threaded mode**<br />
+  Using the `--threads=[X]` command line option will run Psalm's analysis stage on [X] threads. Useful for large codebases, it has a massive impact on performance.
+
+- **Incremental checks**<br />
+  When using the `--diff` command line option, Psalm will only analyse files that have changed *and* files that reference them.
+
+## Example output
+
+```php
+// somefile.php
+<?php
+$a = ['foo', 'bar'];
+echo implode($a, ' ');
+```
+
+```bash
+> ./vendor/bin/psalm somefile.php
+ERROR: InvalidArgument - somefile.php:3:14 - Argument 1 of implode expects `string`, `array` provided
+```
+
+## Inspirations
+
+There are two main inspirations for Psalm:
+ - Etsy's [Phan](https://github.com/etsy/phan), which uses nikic's [`php-ast`](https://github.com/nikic/php-ast) extension to create an abstract syntax tree
+ - Facebook's [Hack](http://hacklang.org/), a PHP-like language that supports many advanced typing features natively, so docblocks aren't necessary.

docs/installation.md

@@ -1,6 +1,6 @@
 # Installation
 
-Psalm Requires PHP >= 5.4 and [Composer](https://getcomposer.org/).
+Psalm Requires PHP >= 5.6 and [Composer](https://getcomposer.org/).
 
 ```bash
 > composer require --dev "vimeo/psalm:dev-master"