diff --git a/README.md b/README.md
index 124f486bc..2c919b68d 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,7 @@ A complete toolkit for the NEO blockchain, including:
 - [RPC node & client](https://github.com/nspcc-dev/neo-go/tree/master/pkg/rpc/README.md)
 - [RPC client](https://github.com/nspcc-dev/neo-go/blob/master/pkg/rpc/README.md)
 - [CLI tool](https://github.com/nspcc-dev/neo-go/blob/master/docs/cli.md)
-- [Smart contract compiler](https://github.com/nspcc-dev/neo-go/blob/master/pkg/vm/compiler/README.md)
+- [Smart contract compiler](https://github.com/nspcc-dev/neo-go/blob/master/docs/compiler.md)
 - [NEO virtual machine](https://github.com/nspcc-dev/neo-go/blob/master/pkg/vm/README.md)
 
 # Getting started
diff --git a/pkg/vm/compiler/README.md b/docs/compiler.md
similarity index 84%
rename from pkg/vm/compiler/README.md
rename to docs/compiler.md
index 88287451e..7d44bfa67 100644
--- a/pkg/vm/compiler/README.md
+++ b/docs/compiler.md
@@ -23,32 +23,41 @@ The neo-go compiler compiles Go programs to bytecode that the NEO virtual machin
 - append
 
 ### VM API (interop layer)
-- storage
-- runtime
-- block
-- header
-- transaction
+Compiler translates interop function calls into NEO VM syscalls or (for custom
+functions) into NEO VM instructions. [Refer to GoDoc](https://godoc.org/github.com/nspcc-dev/neo-go/pkg/interop) for full API documentation.
+
+#### Standard NEO Smart Contract API
+- account
 - asset
+- attribute
+- block
 - blockchain
+- contract
+- engine
+- header
+- input
+- iterator
+- output
+- runtime
+- storage
+- transaction
 
-### VM utility helper functions
-- SHA1
-- SHA256
-- Hash256
-- Hash160
-- other..
-
-### Custom utility functions
-- `FromAddress(address string) []byte`
-
-## Not yet implemented
-- very small part of the interop layer (VM API)
+#### Custom VM utility helper functions
+- crypto:
+  - `SHA1`
+  - `SHA256`
+  - `Hash256`
+  - `Hash160`
+- enumerator
+- util:
+  - `Equals` (to emit `EQUALS` opcode, not needed usually)
+  - `FromAddress(address string) []byte`
 
 ## Not supported
 Due to the limitations of the NEO virtual machine, features listed below will not be supported.
 - channels 
 - goroutines
-- multiple returns 
+- returning multiple values from functions
 
 ## Quick start
 
@@ -125,8 +134,12 @@ Will output something like:
 
 ```
 
+At the moment this is implemented via RPC call to the remote server.
+
 ## Smart contract examples
 
+Some examples are provided in the [examples directory](https://github.com/nspcc-dev/neo-go/tree/master/examples).
+
 ### Check if the invoker of the contract is the owning address
 
 ```Golang
@@ -214,4 +227,3 @@ func Main(operation string, args []interface{}) bool {
 2. Create an issue on Github 
 3. Make a PR with a reference to the created issue, containing the testcase that proves the bug
 4. Either you fix the bug yourself or wait for patch that solves the problem
-