diff --git a/.images/cargo-contract.svg b/.images/cargo-contract.svg
new file mode 100644
index 0000000000000000000000000000000000000000..61f1acde68b12f6f11b83aec68354026f6134a82
--- /dev/null
+++ b/.images/cargo-contract.svg
@@ -0,0 +1,103 @@
+
+
diff --git a/.images/ink-squid.svg b/.images/ink-squid.svg
new file mode 100644
index 0000000000000000000000000000000000000000..3058c42302fc7d5d4e02b334798c47712dd3dc70
--- /dev/null
+++ b/.images/ink-squid.svg
@@ -0,0 +1 @@
+
\ No newline at end of file
diff --git a/README.md b/README.md
index 72d96b8613d02bc41d9b461a7c1630f276d849bf..c57dc5a3109aa476ea5a84428f67ccb2a95ad3a1 100644
--- a/README.md
+++ b/README.md
@@ -1,75 +1,97 @@
-# Cargo plugin for [`ink!`](https://github.com/paritytech/ink) contracts
+
+
-[![GitHub license](https://img.shields.io/github/license/paritytech/cargo-contract)](LICENSE)
-[![GitLab Status](https://gitlab.parity.io/parity/cargo-contract/badges/master/pipeline.svg)](https://gitlab.parity.io/parity/cargo-contract/pipelines)
-[![Latest Version](https://img.shields.io/crates/v/cargo-contract.svg)](https://crates.io/crates/cargo-contract)
+[![CI Status][a1]][a2]
+[![Matrix Chat][b1]][b2]
+[![Discord Chat][c1]][c2]
+[![Latest Release][d1]][d2]
-A CLI tool for helping setting up and managing WebAssembly smart contracts written with ink!.
+[a1]: https://gitlab.parity.io/parity/cargo-contract/badges/master/pipeline.svg
+[a2]: https://gitlab.parity.io/parity/cargo-contract/pipelines
+[b1]: https://img.shields.io/badge/matrix-chat-brightgreen.svg?style=flat
+[b2]: https://riot.im/app/#/room/#ink:matrix.parity.io
+[c1]: https://img.shields.io/discord/722223075629727774?style=flat-square&label=discord
+[c2]: https://discord.gg/ztCASQE
+[d1]: https://img.shields.io/crates/v/cargo-contract.svg
+[d2]: https://crates.io/crates/cargo-contract
-## Installation
+
+
+> `cargo-contract` is a CLI tool which helps you develop smart contracts in Parity's ink!. ink! is a Rust [eDSL](https://wiki.haskell.org/Embedded_domain_specific_language) which allows you to write smart contracts for blockchains built on the [Substrate](https://github.com/paritytech/substrate) framework.
+
+
+
-`rust-src` is a prerequisite: `rustup component add rust-src`.
+[Guided Tutorial for Beginners](https://substrate.dev/substrate-contracts-workshop/#/0/building-your-contract) •
+[ink! Documentation Portal](https://paritytech.github.io/ink-docs)
-`binaryen` is a prerequisite as well, we use it for optimizing the contract Wasm.
+
+
-Install [`binaryen`](https://github.com/WebAssembly/binaryen#tools) with a version >= 99.
-Many package managers have it available nowadays:
+More relevant links:
+* Talk to us on [Element][b2] or [Discord][c2]
+* [`ink!`](https://github.com/paritytech/ink) ‒ The main ink! repository with smart contract examples
+* [Canvas UI](https://paritytech.github.io/canvas-ui/#/upload) ‒ Frontend for contract deployment and interaction
+* [Canvas Node](https://github.com/paritytech/canvas-node) ‒ Simple Substrate blockchain which includes smart contract functionality
+
+
+## Installation
-* [Debian/Ubuntu](https://tracker.debian.org/pkg/binaryen): `apt-get install binaryen`
-* [Homebrew](https://formulae.brew.sh/formula/binaryen): `brew install binaryen`
-* [Arch Linux](https://archlinux.org/packages/community/x86_64/binaryen/): `pacman -S binaryen`
-* Windows: [binary releases are available](https://github.com/WebAssembly/binaryen/releases)
+* Step 1: `rustup component add rust-src`.
+
+* Step 2: Install `binaryen` in a version >= 99:
+
+ * [Debian/Ubuntu](https://tracker.debian.org/pkg/binaryen): `apt-get install binaryen`
+ * [Homebrew](https://formulae.brew.sh/formula/binaryen): `brew install binaryen`
+ * [Arch Linux](https://archlinux.org/packages/community/x86_64/binaryen/): `pacman -S binaryen`
+ * Windows: [binary releases are available](https://github.com/WebAssembly/binaryen/releases)
+
+ There's only an old version in your distributions package manager? Just use a
+ [binary release](https://github.com/WebAssembly/binaryen/releases).
-After you've installed the package execute `cargo install --force cargo-contract`.
+* Step 3: `cargo install --force cargo-contract`
-## Usage
-```
-cargo-contract 0.11.0
-Utilities to develop Wasm smart contracts
+## Usage
-USAGE:
- cargo contract
+You can always use `cargo contract help` to print information on available
+commands and their usage.
-OPTIONS:
- -h, --help Prints help information
- -V, --version Prints version information
+For each command there is also a `--help` flag with info on additional parameters,
+e.g. `cargo contract new --help`.
-SUBCOMMANDS:
- new Setup and create a new smart contract project
- build Compiles the contract, generates metadata, bundles
- both together in a `.contract` file
- check Check that the code builds as Wasm; does not output any
- `.contract` artifact to the `target/` directory
- test Test the smart contract off-chain
- deploy Upload the smart contract code to the chain
- instantiate Instantiate a deployed smart contract
- help Prints this message or the help of the given subcommand(s)
-```
+##### `cargo contract new my_contract`
-## `build` requires the `nightly` toolchain
+Creates an initial smart contract with some scaffolding code into a new
+folder `my_contract` .
-`cargo contract build` must be run using the `nightly` toolchain. If you have
-[`rustup`](https://github.com/rust-lang/rustup) installed, the simplest way to do so is `cargo +nightly contract build`.
-To avoid having to add `+nightly` you can also create a `rust-toolchain` file in your local directory containing
-`nightly`. Read more about how to [specify the rustup toolchain](https://github.com/rust-lang/rustup#override-precedence).
+The contract contains the source code for the [`Flipper`](https://github.com/paritytech/ink/blob/master/examples/flipper/lib.rs)
+contract, which is about the simplest "smart" contract you can build ‒ a `bool` which gets flipped
+from `true` to `false` through the `flip()` function.
-### Note
+##### `cargo +nightly contract build`
-The latest version of `cargo-contract` supports all nightlies after `2020-07-30`, because of a change in the directory
-structure of the `rust-src` component.
+Compiles the contract into optimized WebAssembly bytecode, generates metadata for it,
+and bundles both together in a `.contract` file, which you can use for
+deploying the contract on-chain.
-## Features
+`cargo contract build` must be run using the `nightly` toolchain. If you have
+[`rustup`](https://github.com/rust-lang/rustup) installed, the simplest way to
+do so is `cargo +nightly contract build`.
-The `deploy` and `instantiate` subcommands are **disabled by default**, since they are not fully stable yet and increase the build time.
+To avoid having to always add `+nightly` you can also set `nightly` as the default
+toolchain of a directory by executing `rustup override set nightly` in it.
-If you want to try them, you need to enable the `extrinsics` feature:
+##### `cargo contract check`
-`cargo install --git https://github.com/paritytech/cargo-contract cargo-contract --features extrinsics --force`
+Checks that the code builds as WebAssembly. This command does not output any `.contract`
+artifact to the `target/` directory.
-Once they are stable and the compilation time is acceptable, we will consider removing the `extrinsics` feature.
## License
-The entire code within this repository is licensed under the [GPLv3](LICENSE). Please [contact us](https://www.parity.io/contact/) if you have questions about the licensing of our products.
+The entire code within this repository is licensed under the [GPLv3](LICENSE).
+
+Please [contact us](https://www.parity.io/contact/) if you have questions about
+the licensing of our products.