diff --git a/README.md b/README.md
index 32d4fc05..96b16e40 100644
--- a/README.md
+++ b/README.md
@@ -1,140 +1,233 @@
-# Half-Life SDK for Xash3D [![Build Status](https://github.com/FWGS/hlsdk-xash3d/actions/workflows/.github.yml/badge.svg?branch=master)](https://github.com/FWGS/hlsdk-xash3d/actions/workflows/.github.yml) [![Windows Build Status](https://ci.appveyor.com/api/projects/status/github/FWGS/hlsdk-xash3d?svg=true)](https://ci.appveyor.com/project/a1batross/hlsdk-xash3d)
+# Half-Life SDK for GoldSource and Xash3D [![Build Status](https://github.com/FWGS/hlsdk-xash3d/actions/workflows/.github.yml/badge.svg?branch=master)](https://github.com/FWGS/hlsdk-xash3d/actions/workflows/.github.yml) [![Windows Build Status](https://ci.appveyor.com/api/projects/status/github/FWGS/hlsdk-xash3d?svg=true)](https://ci.appveyor.com/project/a1batross/hlsdk-xash3d)
 
-Half-Life SDK for Xash3D & GoldSource with some fixes.
+Half-Life SDK for GoldSource & Xash3D with some bugfixes.
 
-## How to build
+# Obtaining source code
 
-### CMake as most universal way
+Either clone the repository via [git](`https://git-scm.com/downloads`) or just download ZIP via **Code** button on github. The first option is more preferable as it also allows you to search through the repo history, switch between branches and clone the vgui submodule.
 
-    mkdir build && cd build
-    cmake ../
-    make
+To clone the repository with git type in Git Bash (on Windows) or in terminal (on Unix-like operating systems):
 
-Crosscompiling using mingw:
-
-    mkdir build-mingw && cd build-mingw
-    TOOLCHAIN_PREFIX=i686-w64-mingw32 # check up the actual mingw prefix of your mingw installation
-    cmake ../ -DCMAKE_SYSTEM_NAME=Windows -DCMAKE_C_COMPILER="$TOOLCHAIN_PREFIX-gcc" -DCMAKE_CXX_COMPILER="$TOOLCHAIN_PREFIX-g++"
+```
+git clone --recursive https://github.com/FWGS/hlsdk-xash3d
+```
 
-You may enable or disable some build options by -Dkey=value. All available build options are defined in CMakeLists.txt at root directory.
-See below if you want to build the GoldSource compatible libraries.
+# Build Instructions
 
-See below, if CMake is not suitable for you:
+## Windows. Using Developer Command Propmt for Visual Studio
 
-### Windows
+### Prerequisites
 
-#### Using msvc
+Install and run [Visual Studio Installer](https://visualstudio.microsoft.com/downloads/). The installer allows you to choose specific components. Select `Desktop development with C++`. You can untick everything you don't need in Installation details, but you must keep `MSVC` and `C++ CMake tools for Windows` ticked.
 
-We use compilers provided with Microsoft Visual Studio 6. There're `compile.bat` scripts in both `cl_dll` and `dlls` directories.
-Before running any of those files you must define `MSVCDir` variable which is the path to your msvc installation.
+### Building
 
-    set MSVCDir=C:\Program Files\Microsoft Visual Studio
-    compile.bat
+Run `Developer command prompt for VS` via Windows `Start` menu. Inside the prompt navigate to the hlsdk directory, using `cd` command, e.g.
+```
+cd C:\Users\username\projects\hlsdk-xash3d
+```
 
-These scripts also can be ran via wine:
+Note: if hlsdk-xash3d is unpacked on another disk, nagivate there first:
+```
+D:
+cd projects\hlsdk-xash3d
+```
 
-    MSVCDir="z:\home\$USER\.wine\drive_c\Program Files\Microsoft Visual Studio" wine cmd /c compile.bat
+Сonfigure the project:
+```
+cmake -A Win32 -B build -DCMAKE_INSTALL_PREFIX="dist"
+```
+Once you configure the project you don't need to call `cmake` anymore unless you modify `CMakeLists.txt` files or want to reconfigure the project with different parameters.
 
-The libraries built this way are always GoldSource compatible.
+The next step is to compile the libraries:
+```
+msbuild -verbosity:normal /property:Configuration=Release build/INSTALL.vcxproj
+```
+`hl.dll` and `client.dll` will appear in the directory configured via **CMAKE_INSTALL_PREFIX** option (**dist** in this example).
 
-#### Using mingw
+If you have a mod and want to automatically install libraries to the mod directory, set **GAMEDIR** variable to the directory name and **CMAKE_INSTALL_PREFIX** to your Half-Life or Xash3D installation path:
+```
+cmake -A Win32 -B build -DGAMEDIR=mod -DCMAKE_INSTALL_PREFIX="C:\Program Files (x86)\Steam\steamapps\common\Half-Life"
+```
+Then call `msbuild` as described above.
 
-TODO
+#### Choosing Visual Studio version
 
-### Unix-like
+You can explicitly choose a Visual Studio version on the configuration step by specifying cmake generator:
+```
+cmake -G "Visual Studio 16 2019" -A Win32 -B build -DCMAKE_INSTALL_PREFIX="dist"
+```
 
-To use waf, you need to install python (2.7 minimum)
+### Editing code in Visual Studio
 
-    (./waf configure -T release)
-    (./waf)
+After the configuration step, `HLSDK-XASH3D.sln` should appear in the `build` directory. You can open this solution in Visual Studio and continue developing there.
 
-### Android
+## Windows. Using Microsoft Visual Studio 6
 
-Just typical `ndk-build`.
-TODO: describe what it is.
+Microsoft Visual Studio 6 is very old, but if you still have it installed, you can use it to build this hlsdk. There are no project files, but two `.bat` files, for server and client libraries. They require variable **MSVCDir** to be set to the installation path of Visual Studio:
 
-### Building GoldSource-compatible libraries
+```
+set MSVCDir=C:\Program Files\Microsoft Visual Studio
+cd dlls && compile.bat && cd ../cl_dll && compile.bat
+```
 
-To enable building the goldsource compatible client library add GOLDSOURCE_SUPPORT flag when calling cmake:
+`hl.dll` and `client.dll` will appear in `dlls/` and `cl_dll/` diretories. The libraries built with msvc6 should be compatible with Windows XP.
 
-    cmake .. -DGOLDSOURCE_SUPPORT=ON
+## Linux. Using Steam Runtime in chroot
 
-or when using waf:
+### Prerequisites
 
-     ./waf configure -T release --enable-goldsrc-support
+The official way to build Steam compatible games for Linux is through steam-runtime.
 
-Unlike original client by Valve the resulting client library will not depend on vgui or SDL2 just like the one that's used in FWGS Xash3d.
+Install schroot. On Ubuntu or Debian:
 
-Note for **Windows**: it's not possible to create GoldSource compatible libraries using mingw, only msvc builds will work.
+```
+sudo apt install schroot
+```
 
-Note for **Linux**: GoldSource requires libraries (both client and server) to be compiled with libstdc++ bundled with g++ of major version 4 (versions from 4.6 to 4.9 should work).
-If your Linux distribution does not provide compatible g++ version you have several options.
+Clone https://github.com/ValveSoftware/steam-runtime and follow instructions: [download](https://github.com/ValveSoftware/steam-runtime/blob/e014a74f60b45a861d38a867b1c81efe8484f77a/README.md#downloading-a-steam-runtime) and [setup](https://github.com/ValveSoftware/steam-runtime/blob/e014a74f60b45a861d38a867b1c81efe8484f77a/README.md#using-schroot) the chroot.
 
-#### Method 1: Statically build with c++ library
+```
+sudo ./setup_chroot.sh --i386 --tarball ./com.valvesoftware.SteamRuntime.Sdk-i386-scout-sysroot.tar.gz
+```
 
-This one is the most simple but has a drawback.
+### Building
 
-    cmake ../ -DGOLDSOURCE_SUPPORT=ON -DCMAKE_C_FLAGS="-static-libstdc++ -static-libgcc"
+Now you can use cmake and make prepending the commands with `schroot --chroot steamrt_scout_i386 --`:
+```
+mkdir build-in-steamrt && cd build-in-steamrt
+schroot --chroot steamrt_scout_i386 -- cmake ..
+schroot --chroot steamrt_scout_i386 -- make
+```
 
-The drawback is that the compiled libraries will be larger in size.
+## Linux. Build without Steam Runtime
 
-#### Method 2: Build in Steam Runtime chroot
+### Prerequisites
 
-This is the official way to build Steam compatible games for Linux.
+Install C++ compilers, cmake and x86 development libraries for C, C++ and SDL2. On Ubuntu/Debian:
+```
+sudo apt install cmake build-essential gcc-multilib g++-multilib libsdl2-dev:i386
+```
 
-Clone https://github.com/ValveSoftware/steam-runtime and follow instructions https://github.com/ValveSoftware/steam-runtime#building-in-the-runtime
+### Building
 
-    sudo ./setup_chroot.sh --i386
+```
+mkdir build && cd build
+cmake ..
+make
+```
 
-Then use cmake and make as usual, but prepend the commands with `schroot --chroot steamrt_scout_i386 --`:
+Note that the libraries built this way might be not compatible with Steam Half-Life. If you have such issue you can configure it to build statically with c++ and gcc libraries:
+```
+cmake .. -DCMAKE_C_FLAGS="-static-libstdc++ -static-libgcc"
+```
+To ensure portability it's still better to build using Steam Runtime or another chroot of some older distro.
 
-    mkdir build-in-steamrt && cd build-in-steamrt
-    schroot --chroot steamrt_scout_i386 -- cmake ../ -DGOLDSOURCE_SUPPORT=ON
-    schroot --chroot steamrt_scout_i386 -- make
+## Linux. Build in your own chroot
 
-#### Method 3: Create your own chroot with older distro that includes g++ 4.
+### Prerequisites
 
-Use the most suitable way for you to create an old distro 32-bit chroot. E.g. on Debian (and similar) you can use debootstrap.
+Use the most suitable way for you to create an old distro 32-bit chroot. E.g. on Ubuntu/Debian you can use debootstrap.
 
-    sudo debootstrap --arch=i386 jessie /var/chroot/jessie-debian-i386 # On Ubuntu type trusty instead of jessie
-    sudo chroot /var/chroot/jessie-debian-i386
+```
+sudo apt install debootstrap schroot
+sudo mkdir -p /var/choots
+sudo debootstrap --arch=i386 jessie /var/chroots/jessie-i386 # On Ubuntu type trusty instead of jessie
+sudo chroot /var/chroots/jessie-i386
+```
 
-Inside chroot install cmake, make, g++ and libsdl2-dev. Then exit the chroot.
+```
+# inside chroot
+apt install cmake build-essential gcc-multilib g++-multilib libsdl2-dev
+exit
+```
 
-On the host system install schroot. Then create and adapt the following config in /etc/schroot/chroot.d/jessie.conf (you can choose a different name):
+Create and adapt the following config in /etc/schroot/chroot.d/jessie.conf (you can choose a different name):
 
 ```
 [jessie]
 type=directory
 description=Debian jessie i386
-directory=/var/chroot/debian-jessie-i386/
+directory=/var/chroots/jessie-i386/
 users=yourusername
-groups=yourusername
+groups=adm
 root-groups=root
 preserve-environment=true
 personality=linux32
 ```
 
-Insert your actual user name in place of `yourusername`. Then prepend any make or cmake call with `schroot -c jessie --`:
+Insert your actual user name in place of `yourusername`.
 
-    mkdir build-in-chroot && cd build-in-chroot
-    schroot --chroot jessie -- cmake ../ -DGOLDSOURCE_SUPPORT=ON
-    schroot --chroot jessie -- make
+### Building
 
-#### Method 4:  Install the needed g++ version yourself
+Prepend any make or cmake call with `schroot -c jessie --`:
+```
+mkdir build-in-chroot && cd build-in-chroot
+schroot --chroot jessie -- cmake ..
+schroot --chroot jessie -- make
+```
 
-TODO: describe steps.
+## Linux. Crosscompiling using mingw
 
-#### Configuring Qt Creator to use toolchain from chroot
+Note that GoldSource won't work with libraries compiled with mingw.
 
-Create a file with the following contents anywhere:
+TODO: do we need this section at all? Is Xash3D-FWGS distributed with support for game libraries built with mingw?
 
-```sh
-#!/bin/sh
-schroot --chroot steamrt_scout_i386 -- cmake "$@"
+### Prerequisites
+
+Install mingw. On Ubuntu/Debian:
+```
+sudo apt-get install -y mingw-w64-i686-dev binutils-mingw-w64-i686 gcc-mingw-w64-i686 g++-mingw-w64-i686
+```
+
+### Building
+
+```
+mkdir build-mingw && cd build-mingw
+TOOLCHAIN_PREFIX=i686-w64-mingw32 # check up the actual mingw prefix of your mingw installation
+cmake .. -DCMAKE_SYSTEM_NAME=Windows -DCMAKE_C_COMPILER="$TOOLCHAIN_PREFIX-gcc" -DCMAKE_CXX_COMPILER="$TOOLCHAIN_PREFIX-g++"
 ```
 
-Make it executable.
-In Qt Creator go to `Tools` -> `Options` -> `Build & Run` -> `CMake`. Add a new cmake tool and specify the path of previously created file.
-Go to `Kits` tab, clone your default configuration and choose your CMake tool there.
-Choose the new kit when opening CMakeLists.txt.
+## Android
+
+TODO
+
+## Other platforms
+
+Building on other Unix-like platforms (e.g. FreeBSD) is supported.
+
+### Prerequisites
+
+Install C and C++ compilers (like gcc or clang), cmake and make (or gmake)
+
+### Building
+
+```
+mkdir build && cd build
+cmake ..
+make
+```
+
+### Building with waf
+
+To use waf, you need to install python (2.7 minimum)
+
+```
+(./waf configure -T release)
+(./waf)
+```
+
+## Build options
+
+Some useful build options that can be set during the cmake step.
+
+* **GOLDSOURCE_SUPPORT** - allows to turn off/on the support for GoldSource input. Set to **ON** by default on Windows and Linux, **OFF** on other platforms.
+* **USE_VGUI** - whether to use VGUI library. **OFF** by default. You need to init `vgui_support` submodule in order to build with VGUI.
+
+This list is incomplete. Look at `CMakeLists.txt` to see all available options.
+
+Prepend option names with `-D` when passing to cmake. Boolean options can take values **OFF** and **ON**. Example:
+
+```
+cmake .. -DUSE_VGUI=ON -DGOLDSOURCE_SUPPORT=ON -DCROWBAR_IDLE_ANIM=ON -DCROWBAR_FIX_RAPID_CROWBAR=ON
+```