diff --git a/.gitignore b/.gitignore
index c54fba0..d874750 100644
--- a/.gitignore
+++ b/.gitignore
@@ -7,4 +7,4 @@
 .vscode
 .vscode
 _build
-_build_html
+sphinx
diff --git a/README.md b/README.md
index 89a7e88..b6ac6a3 100644
--- a/README.md
+++ b/README.md
@@ -1,48 +1,75 @@
 # Documentation project for NetXMS
 
-Components:
+This repository contains the source files for the official [NetXMS](https://netxms.com) documentation.
 
--   concept/ - System concept, architecture, and terminology.
--   admin/ - In-depth administrator guide.
--   developer/ - Describes development process and possible ways of extending NetXMS.
--   manpages/ - UNIX man pages.
+NXSL (scripting) documentation sources are in the [separate repository](https://github.com/netxms/nxsl-doc).
+
+Components of the documentation are stored in the following directories:
+
+- concept/ - System concept, architecture, and terminology (partially outdated and moved to admin guide).
+- admin/ - In-depth administrator guide.
+- developer/ - Describes development process and possible ways of extending NetXMS.
+- manpages/ - UNIX man pages.
 
 # Notes
 
-## Local setup
+## Prerequisites
+
+### macOS
+
+```shell
+brew cask install basictex
+sudo tlmgr update --self
+sudo tlmgr install latexmk fncychap titlesec tabulary varwidth framed wrapfig capt-of needspace helvetic courier letltxmacro tex-gyre
+```
+
+### Ubuntu/Mint
 
--   mkvirtualenv sphinx
--   workon sphinx
--   pip install -r requirements.txt
+```shell
+apt install python3-pip python3-virtualenv latexmk texlive-latex-extra git
+```
 
-## Ubuntu/Mint
+## Preparing the environment
 
--   apt install python3-pip python3-virtualenv latexmk texlive-latex-extra git
--   git clone https://github.com/netxms/netxms-doc
--   cd netxms-doc
--   python3 -m virtualenv .
--   . bin/activate # activate virtualenv
--   pip install -r requirements.txt
+```shell
+git clone https://github.com/netxms/netxms-doc
 
-## macOS specific
+python3 -m venv sphinx # create virtualenv, do it once
+source sphinx/bin/activate # activate virtualenv
+pip3 install -r requirements.txt # install dependencies, do it once
+```
 
--   brew cask install basictex
--   sudo tlmgr update --self
--   sudo tlmgr install latexmk fncychap titlesec tabulary varwidth framed wrapfig capt-of needspace helvetic courier letltxmacro tex-gyre
+## Building locally
+
+```shell
+cd netxms-doc
+source sphinx/bin/activate # activate virtualenv
+make html pdf
+```
 
 ## Automatic rebuild and reload
 
--   cd admin && sphinx-autobuild . \_build_html
+```shell
+cd netxms-doc
+cd admin
+sphinx-autobuild -b html . _build/html
+```
 
 ## Building translated version:
 
--   make gettext
--   sphinx-intl update -p \_build/locale -l ru
--   sphinx-intl build
--   make -e SPHINXOPTS="-D language=ru" html
+Note: translated documentation is not updated anymore and is kept for reference only.
+
+```shell
+make gettext
+sphinx-intl update -p _build/locale -l ru
+sphinx-intl build
+make -e SPHINXOPTS="-D language=ru" html
+```
 
 # Useful links
 
 http://sphinx-doc.org/markup/para.html
+
 http://sphinx-doc.org/markup/inline.html
+
 http://sphinx-doc.org/markup/