diff --git a/README.md b/README.md
index 08f0157..0ac0e3e 100644
--- a/README.md
+++ b/README.md
@@ -202,7 +202,8 @@ RSpec.configure do |config|
       swagger: '2.0',
       info: {
         title: 'API V1',
-        version: 'v1'
+        version: 'v1',
+        description: 'This is the first version of my API'
       },
       basePath: '/api/v1'
     },
@@ -211,7 +212,8 @@ RSpec.configure do |config|
       swagger: '2.0',
       info: {
         title: 'API V2',
-        version: 'v2'
+        version: 'v2',
+        description: 'This is the second version of my API'
       },
       basePath: '/api/v2'
     }
@@ -219,7 +221,8 @@ RSpec.configure do |config|
 end
 ```
 
-__NOTE__: By default, the paths, operations and responses defined in your spec files will be associated with the first Swagger document in _swagger_helper.rb_. If you're using multiple documents, you'll need to tag the individual specs with their target document name:
+#### Supporting multiple versions of API #### 
+By default, the paths, operations and responses defined in your spec files will be associated with the first Swagger document in _swagger_helper.rb_. If your API has multiple versions, you should be using separate documents to describe each of them. In order to assign a file with a given version of API, you'll need to add the ```swagger_doc``` tag to each spec specifying its target document name:
 
 ```ruby
 # spec/integration/v2/blogs_spec.rb
@@ -233,6 +236,25 @@ describe 'Blogs API', swagger_doc: 'v2/swagger.json' do
 end
 ```
 
+#### Formatting the description literals: #### 
+Swagger supports the Markdown syntax to format strings. This can be especially handy if you were to provide a long description of a given API version or endpoint. Use [this guide](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet) for reference. 
+
+__NOTE:__ There is one difference between the official Markdown syntax and Swagger interpretation, namely tables. To create a table like this:
+
+| Column1 | Collumn2 |
+| ------- | -------- |
+| cell1   | cell2    | 
+
+you should use the folowing syntax, making sure there are no whitespaces at the start of any of the lines:
+
+```
+
+| Column1 | Collumn2 |
+| ------- | -------- |
+| cell1   | cell2    |
+
+```
+
 ### Specifying/Testing API Security ###
 
 Swagger allows for the specification of different security schemes and their applicability to operations in an API. To leverage this in rswag, you define the schemes globally in _swagger_helper.rb_ and then use the "security" attribute at the operation level to specify which schemes, if any, are applicable to that operation. Swagger supports :basic, :apiKey and :oauth2 scheme types. See [the spec](http://swagger.io/specification/#security-definitions-object-109) for more info.