diff --git a/.vscode/spellright.dict b/.vscode/spellright.dict
new file mode 100644
index 0000000..37868ae
--- /dev/null
+++ b/.vscode/spellright.dict
@@ -0,0 +1,2 @@
+md
+on-prem
diff --git a/README.md b/README.md
index 9e0039d..dbf291b 100644
--- a/README.md
+++ b/README.md
@@ -11,8 +11,12 @@ a new page (under given parent) or update an existing one.
 
 It's as easy as:
 
-```
+```sh
 $ pip install confluence.md
+
+# If the above doesn't work, your `pip` command points to different
+# python than installation than `python` command. If so, run:
+$ python -m pip install confluence.md
 ```
 
 ## How to use it in command-line?
@@ -21,22 +25,36 @@ Markdown to Confluence
 
 Example workflow:
 
-### 1. Create a new page under `--parent_id`:
-```
-$ confluence.md --user user@name.net --token 9a8dsadsh --url https://your-domain.atlassian.net \
-        create --file README.md --parent_id 182371 --title "new title" --add_meta
+#### 1. Create page
+
+Create a new page under `--parent_id`:
+```sh
+$ confluence.md --user user@name.net \             # Atlassian username
+        --token 9a8dsadsh \                        # API token or --password
+        --url https://your-domain.atlassian.net \  # Confluence instance URL
+        create \                                   # create or update
+        --file README.md \                         # markdown file
+        --parent_id 182371 \                       # parent page
+        --title "new title"                        # title for a new page
+        --add_meta                                 # adds meta to source.md file
 ```
 
-### 2. The page is created and the file is decorated with metadata:
-```
+#### 2. Verify markdown
+
+The page is created and the file is decorated with metadata:
+
+```sh
 $ head -n 3 markdown.md
 ---
 confluence-url: https://your-domain.atlassian.net/wiki/spaces/SP/pages/18237182/new+title
 ---
 ```
 
-### 3. Performing an update does not require providing `--page_id` and `--url`:
-```
+#### 3. Update page
+
+Performing an update does not require providing `--page_id` and `--url`:
+
+```sh
 $ confluence.md --user user@name.net --token 9a8dsadsh update --file README.md
 ```
 
@@ -46,6 +64,8 @@ Consider adding useful `--add_info` option.
 
 To create Atlassian API Token go to [api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
 
+## Command line arguments
+
 **Actions:**
 
 - `update`    		Updates page content based on given `page_id` or metadata in Markdown file
@@ -73,7 +93,7 @@ To create Atlassian API Token go to [api-tokens](https://id.atlassian.com/manage
 - `-t` `TOKEN`, `--token` `TOKEN` Atlassian API token
 - `-p` `PWD`, `--password` `PWD`  Atlassian password (used in on-prem instances)
 - `-l` `URL`, `--url` `URL`       Atlassian instance URL
-- `-n`, `--no_verify_ssl`         Don't verify SSL cert in on-prem instances
+- `-n`, `--no_verify_ssl`         don't verify SSL cert (useful in on-prem instances)
 
 **create page parameters:**
 
@@ -83,7 +103,7 @@ To create Atlassian API Token go to [api-tokens](https://id.atlassian.com/manage
 
 **update page arguments:**
 
--  `--page_id` `PAGE_ID`     define (or override) page id while updating a page
+- `--page_id` `PAGE_ID`     define (or override) page id while updating a page
 
 ## How to use it in a Python script?
 
@@ -92,12 +112,16 @@ it in a Python script. See this example:
 
 ```python
 from md2cf.utils.confluencemd import ConfluenceMD
+
 conf_md = ConfluenceMD(username=user,
                        md_file=md_file,
                        token=token,
                        url=url,
                        convert_jira=convert_jira)
-conf_md.create_new("page_id", "title")
-# or
-conf_md.update_existing("page_id")
+
+# create new page under parent_id
+new_page_id = conf_md.create_new("parent_id", "title")
+
+# update existing page with given page_id
+page_id = conf_md.update_existing("page_id")
 ```
\ No newline at end of file