Update the documentation UX

README.md

@@ -24,98 +24,133 @@ Prepare dev environment prerequisites: see [docs/setup-dev.md](docs/setup-dev.md
 
 Setup:
 
-```
+```sh
 zksync dev-up
 zksync init
 ```
 
 To completely reset the dev environment:
 
 - Stop services:
-```zksync dev-down```
+  ```sh
+  zksync dev-down
+  ```
 - Repeat the setup procedure above
 
 # (Re)deploy db and contraсts:
 
-```zksync redeploy```
+```sh
+zksync redeploy
+```
 
 ## Environment configurations
 
 Env config files are held in `etc/env/`
 
 List configurations:
 
-```zksync env```
+```sh
+zksync env
+```
 
 Switch between configurations:
 
-```zksync env <ENV_NAME>```
+```sh
+zksync env <ENV_NAME>
+```
 
 ## Monitoring & management:
 
 Seed for Metamask: fine music test violin matrix prize squirrel panther purchase material script deal
-Geth: ```geth attach $(bin/kube-geth-url)```
+Geth:
+
+```sh
+geth attach $(bin/kube-geth-url)
+```
 
 NOTE: if you are resetting geth, each Metamask account must be manually reset via Settings > Advanced > Reset account.
 
 ## Build and run server + prover locally for development:
 
 Run server:
-```
+
+```sh
 zksync server
 ```
 
-By default block chunk size set to `100`. For testing & development purposes you
-ca change it to smaller values. Two places requires a change:
-1. Environment variable value in `./etc/env/dev.env` `BLOCK_SIZE_CHUNKS`
-2. Rust constant at `./core/models/params.rs` `BLOCK_SIZE_CHUNKS`
-If you apply changes, do not forget to redeploy contracts `zksync redeploy`.
+By default block chunk size set to `50`. For testing & development purposes you
+can change it to the smaller value (`18` should be enough).
 
-You must prepare keys. This only needs to be done once:
+To do so, change the environment variable `BLOCK_SIZE_CHUNKS` value in `./etc/env/dev.env`.
+
+After that you may need to invalidate `cargo` cache by touching the files of `models`:
+
+```sh
+touch core/models/**/*.rs
 ```
+
+This is required, because `models` take the environment variable value at the compile time, and
+we have to recompile this module to set correct values.
+
+If you use additional caching systems (like `sccache`), you may have to remove their cache as well.
+
+After that you must generate keys. This only needs to be done once:
+
+```sh
 ./bin/gen-keys
 zksync redeploy
 ```
+
 Run prover:
-```
+
+```sh
 zksync prover
 ```
 
 Run client
-```
+
+```sh
 zksync client
 ```
 
 Client UI will be available at http://localhost:8080.
 Make sure you have environment variables set right, you can check it by running:
-```zksync env```. You should see `* dev` in output.
+`zksync env`. You should see `* dev` in output.
 
 ## Build and push images to dockerhub:
 
-```zksync dockerhub-push```
+```sh
+zksync dockerhub-push
+```
 
 # Development
 
 ## Database migrations
 
-- ```cd core/storage```
+- 
+  ```sh
+  cd core/storage
+  ```
 - Add diesel migration
 - Rename `core/storage/schema.rs.generated` to `schema.rs`
-- Run tests: ```zksync db-tests```
+- Run tests:
+  ```sh
+  zksync db-tests
+  ```
 
 ## Generating keys
 
 To generate a proving key, from `server` dir run:
 
-```
+```sh
 cargo run --release --bin read_write_keys
 ```
 
 It will generate a `*VerificationKey.sol` and `*_pk.key` files for 'deposit', 'exit' and 'transfer' circuits in the root folder.
 
 Move files to proper locations:
 
-```shell
+```sh
 mv -f n*VerificationKey.sol ./contracts/contracts/
 mv -f *_pk.key ./prover/keys/
 ```
@@ -126,7 +161,7 @@ If the pregenerated leaf format changes, replace the `EMPTY_TREE_ROOT` constant
 
 ### Re-build contracts:
 
-```
+```sh
 cd contracts; yarn build
 ```
 
@@ -136,7 +171,7 @@ So you need to rebuild the code on every change (to be automated).
 
 ### Publish source code on etherscan
 
-```
+```sh
 zksync publish-source
 ```
 

docs/setup-dev.md

@@ -1,69 +1,149 @@
 # Prerequisites
 
-## Docker
+## `Docker`
 
-Install docker.
+Install `docker`. It is recommended to follow the instructions from the [official site](https://docs.docker.com/install/).
 
-## Node & Yarn
+Installing `docker` via `snap` or from the default repository can cause troubles.
 
-Install Node.
+You need to install both `docker` and `docker-compose`.
 
-Install yarn.
+**Note:** On linux you may encounter the following error when you'll try to work with `zksync`:
 
-`yarn global add @vue/cli-service`
+```sh
+ERROR: Couldn't connect to Docker daemon - you might need to run `docker-machine start default`.
+```
+
+If so, you **do not need** to install `docker-machine`. Most probably, it means that your user
+is not added to the `docker` group. You can check it as follows:
+
+```sh
+docker-compose up # Should raise the same error.
+sudo docker-compose up # Should start doing things.
+```
+
+If the first command fails, but the second succeeds, then you need to add your user to the `docker` group:
+
+```sh
+sudo usermod -a -G docker your_user_name
+```
+
+After that, you should logout and login again (user groups are refreshed after the login).
+The problem should be solved at this step.
+
+## `Node` & `Yarn`
+
+1. Install `Node`.
+
+2. Install `yarn`. Instructions can be found on the [official site](https://classic.yarnpkg.com/en/docs/install/).
+
+3. Run `yarn global add @vue/cli-service`
 
-## Axel
+## `Axel`
 
-Install axel for downloading keys:
+Install `axel` for downloading keys:
 
-```brew install axel```
+On mac:
 
-## gnu-sed for MAC
+```sh
+brew install axel
+```
+
+On debian-based linux:
+
+```sh
+sudo apt-get install axel
+```
 
-`brew install gnu-sed`
+## `gnu-sed`
 
-## Envsubst for mac (to transpile k8s yaml files)
+On mac:
 
+```sh
+brew install gnu-sed
 ```
+
+On linux `sed` is available by default in most cases.
+
+## `Envsubst` (to transpile k8s `yaml` files)
+
+On mac:
+
+```sh
 brew install gettext
 brew link --force gettext 
 ```
 
-## Rust
+On debian-based linux it should be available by default, if not, run:
+
+```sh
+sudo apt-get install gettext
+```
+
+## `Rust`
+
+Install the latest `rust` version.
 
-Install the latest rust version (>= 1.32) https://www.rust-lang.org/tools/install:
+Instructions can be found on the [official site](https://www.rust-lang.org/tools/install).
+
+Verify the `rust` installation:
 
 ```
 rustc --version
-rustc 1.32.0-nightly (21f268495 2018-12-02)
+rustc 1.41.0 (5e1a79984 2020-01-27)
 ```
 
-# JQ
+# `JQ`
+
+`jq` is used to work with JSON when managing DigitalOcean.
 
-jq is used to work with json when managing DigitalOcean.
+On mac:
 
 ```brew install jq```
 
-# envsubst
+On debian-based linux:
 
-```bash
-brew install gettext
-brew link --force gettext 
+```sh
+sudo apt-get install jq
 ```
 
 # PSQL
 
 Install `psql` CLI tool to interact with postgres.
 
-## Diesel
+On debian-based linux:
+
+```sh
+sudo apt-get install postgresql
+```
+
+## `Diesel`
+
+Install [`diesel`](https://diesel.rs/) CLI:
+
+```sh
+cargo install diesel_cli --no-default-features --features postgres
+```
+
+If at the install step you get the linkage errors, install the development version of `libpq`.
+
+On debian-based linux:
 
-```cargo install diesel_cli --no-default-features --features postgres```
+```sh
+sudo apt-get install libpq-dev
+```
+
+## `solc`
+
+You have to install `solc` v0.5.16. Instructions can be found at [readthedocs](https://solidity.readthedocs.io/en/v0.6.2/installing-solidity.html).
+
+The best option for mac is install via `homebrew`, for linux the simplest way is to use `snap`.
 
 ## Environment
 
 Edit the lines below and add them to your shell profile file (e.g. `~/.bash_profile`):
 
-```
+```sh
 # Add path here:
 export ZKSYNC_HOME=/path/to/zksync
 
@@ -73,24 +153,28 @@ export PATH=$ZKSYNC_HOME/bin:$PATH
 # cd $ZKSYNC_HOME
 ```
 
-Autocomplete configuration.
+Autocomplete configuration:
 
-`bash`:
-```
-complete -W "\`grep -oE '^[a-zA-Z0-9_.-]+:([^=]|$)' $ZKSYNC_HOME/Makefile | sed 's/[^a-zA-Z0-9_.-]*$//'\`" zksync
-```
+- `bash`:
 
-`zsh`:
-```
-echo "fpath=(~/.zsh_comp $fpath)" >> ~/.zshrc
+  ```sh
+  complete -W "\`grep -oE '^[a-zA-Z0-9_.-]+:([^=]|$)' $ZKSYNC_HOME/Makefile | sed 's/[^a-zA-Z0-9_.-]*$//'\`" zksync
+  ```
 
-mkdir -p ~/.zsh_comp
-```
-add `~/.zsh_comp/_zksync`:
-```
-#compdef zksync
+- `zsh`:
 
-cmds=( ${(uf)"$(grep -oE '^[a-zA-Z0-9_.-]+:([^=]|$)' $ZKSYNC_HOME/Makefile | sed 's/[^a-zA-Z0-9_.-]*$//')"} )
+  ```sh
+  echo "fpath=(~/.zsh_comp $fpath)" >> ~/.zshrc
+
+  mkdir -p ~/.zsh_comp
+  ```
 
-_describe 'zksync make cmds' cmds
-```
+  add `~/.zsh_comp/_zksync`:
+
+  ```sh
+  #compdef zksync
+
+  cmds=( ${(uf)"$(grep -oE '^[a-zA-Z0-9_.-]+:([^=]|$)' $ZKSYNC_HOME/Makefile | sed 's/[^a-zA-Z0-9_.-]*$//')"} )
+
+  _describe 'zksync make cmds' cmds
+  ```