diff --git a/docs/README.md b/docs/README.md
index e792b4d5e4..1825f364e8 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -14,7 +14,6 @@ To contribute to the documentation, open a GitHub pull request.
 - You need to fork this repository.
 - Work on your fork's task branches, not the `master` branch.
 - Send pull requests to the `master` branch in this repository.
-- Run `make preview` to build the documentation and preview it locally at http://127.0.0.1:5500/.
 - If you want to submit a knowledge base article, see [Submitting a KB Article](#submitting-a-kb-article).
 
 The user documentation is written in reStructuredText (RST) - a plaintext markup language similar to Markdown. If you're not familiar with RST, see [ScyllaDB RST Examples](https://sphinx-theme.scylladb.com/stable/examples/index.html).
@@ -22,12 +21,25 @@ The user documentation is written in reStructuredText (RST) - a plaintext markup
 The developer documentation is written in Markdown. See [Basic Markdown Syntax](https://www.markdownguide.org/basic-syntax/) for reference.
 
 
-## Prerequisites for Building User Documentation
+## Submitting a KB Article
+
+If you are submitting a Knowledgebase Article (KBA), use the following guidelines:
+* In the `/kb_common` directory there is a template for KBAs. It is called `kb-article-template.rst`.
+* Make a copy of this file in the `/kb directory`, saving it with a unique name.
+* Open the template and fill in the required inforation. 
+* Remove what is not needed. 
+* Run`make preview` to make the docs and preview locally.
+* Send a PR - add KBA in the title. 
+
+
+## Building User Documentation
+
+### Prerequisites
 
 * Python 3. Check your version with `$ python --version`
 * Vale CLI (optional to lint docs). [Install Vale](https://docs.errata.ai/vale/install) for your operative system.
 
-### Mac OS X
+#### Mac OS X
 
 You must have a working [Homebrew](http://brew.sh/) in order to install the needed tools.
 
@@ -40,16 +52,30 @@ brew help
 make -h
 ```
 
-### Fedora 29/Debian-based Linux Distributions
+#### Fedora 29/Debian-based Linux Distributions
 
 Building the user docs should work out of the box on Fedora 29.
 
-### Windows
+#### Windows
 
 Use "Bash on Ubuntu on Windows" for the same tools and capabilites as on a debian-based Linux.
+
 Note: livereload seems not working on Windows.
 
-# Lint
+### Building the Docs 
+
+1. Run `make preview` to build the documentation.
+1. Preview the built documentation locally at http://127.0.0.1:5500/.
+
+### Cleanup
+
+You can clean up all the build products and auto-installed Python stuff with:
+
+```sh
+make pristine
+```
+
+### Lint
 
 Lint all:
 
@@ -69,15 +95,7 @@ Lint one folder (e.g. getting-started):
 make proofread path=getting-started
 ```
 
-# Cleanup
-
-You can clean up all the build products and auto-installed Python stuff with:
-
-```sh
-make pristine
-```
-
-# Contributor info
+# Information for Contributors
 
 If you are interested in contributing to Scylla
 docs, please read the Scylla open source page at
@@ -86,17 +104,8 @@ a Scylla contributor agreement if needed.  We can
 only accept documentation pull requests if we have
 a contributor agreement on file for you
 
-# Submitting a KB Article
 
-If you are submitting a Knowledgebase Article (KBA), use the following guidelines:
-* In the `/kb_common` directory there is a template for KBAs. It is called `kb-article-template.rst`.
-* Make a copy of this file in the `/kb directory`, saving it with a unique name.
-* Open the template and fill in the required inforation. 
-* Remove what is not needed. 
-* Run`make preview` to make the docs and preview locally.
-* Send a PR - add KBA in the title. 
-
-# Third-party documentation
+# Third-party Documentation
 
  * Do any copying as a separate commit.  Always commit an unmodified version first and then do any editing in a separate commit.