diff --git a/Gemfile b/Gemfile
new file mode 100644
index 0000000..6d4947a
--- /dev/null
+++ b/Gemfile
@@ -0,0 +1,4 @@
+source 'http://rubygems.org'
+
+gem 'appium_lib', ">=10.5.0"
+gem 'browserstack-local', ">=1.3.0"
\ No newline at end of file
diff --git a/Gemfile.lock b/Gemfile.lock
new file mode 100644
index 0000000..cc945f2
--- /dev/null
+++ b/Gemfile.lock
@@ -0,0 +1,37 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    appium_lib (10.6.0)
+      appium_lib_core (~> 3.3)
+      nokogiri (~> 1.8, >= 1.8.1)
+      tomlrb (~> 1.1)
+    appium_lib_core (3.11.0)
+      faye-websocket (~> 0.11.0)
+      selenium-webdriver (~> 3.14, >= 3.14.1)
+    browserstack-local (1.3.0)
+    childprocess (3.0.0)
+    eventmachine (1.2.7)
+    faye-websocket (0.11.0)
+      eventmachine (>= 0.12.0)
+      websocket-driver (>= 0.5.1)
+    mini_portile2 (2.4.0)
+    nokogiri (1.10.10)
+      mini_portile2 (~> 2.4.0)
+    rubyzip (2.3.0)
+    selenium-webdriver (3.142.7)
+      childprocess (>= 0.5, < 4.0)
+      rubyzip (>= 1.2.2)
+    tomlrb (1.3.0)
+    websocket-driver (0.7.3)
+      websocket-extensions (>= 0.1.0)
+    websocket-extensions (0.1.5)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  appium_lib (>= 10.5.0)
+  browserstack-local (>= 1.3.0)
+
+BUNDLED WITH
+   2.1.4
diff --git a/README.md b/README.md
index 04c006d..400f7ef 100644
--- a/README.md
+++ b/README.md
@@ -1,9 +1,115 @@
 # ruby-appium-app-browserstack
-App Automate Ruby Samples
----------------------
 
-This repository contains code for Automated Native App tests. Please feel free to clone the repo and use the example code.
+This repository demonstrates how to run Appium Ruby tests on BrowserStack App Automate.
 
-For frameworks integration with BrowserStack, refer to their individual repositories -
+## Setup
+
+### Requirements
+
+1. Ruby >=2.6
+
+  - If not installed, install Ruby from [here](https://www.ruby-lang.org/en/documentation/installation/)
+
+2. Dependency Manager `bundler`
+
+  - If not installed, run command `gem install bundler`  
+
+### Install the dependencies
+
+To install the dependencies, run the following command in the project's base directory :
+
+```ruby
+bundle install
+```
+
+**Note**: If you are using Windows, RubyInstaller has a known [issue](https://github.com/oneclick/rubyinstaller2/issues/96). Run the following script as a workaround to resolve it -
+
+```ruby
+gem install ffi
+gem uninstall -aIx eventmachine
+gem install eventmachine --platform=ruby
+```
+
+## Getting Started
+
+Getting Started with Appium tests in Ruby on BrowserStack couldn't be easier!
+
+### Run your first test :
+
+**1. Upload your Android or iOS App**
+Upload your Android app (.apk or .aab file) or iOS app (.ipa file) to BrowserStack servers using our REST API. Here is an example cURL request :
+
+```
+curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
+-X POST "https://api-cloud.browserstack.com/app-automate/upload" \
+-F "file=@/path/to/apk/file"
+```
+
+Ensure that @ symbol is prepended to the file path in the above request. Please note the `app_url` value returned in the API response. We will use this to set the application under test while configuring the test later on.
+
+**Note**: If you do not have an .apk or .ipa file and are looking to simply try App Automate, you can download and test using our [sample Android app](https://www.browserstack.com/app-automate/sample-apps/android/WikipediaSample.apk) or [sample iOS app](https://www.browserstack.com/app-automate/sample-apps/ios/BStackSampleApp.ipa).
+
+**2. Configure and run your first test**
+
+Open `browserstack_sample.rb` file in `android` or `ios` directory :
+
+- Replace `YOUR_USERNAME` & `YOUR_ACCESS_KEY` with your BrowserStack access credentials. Get your BrowserStack access credentials from [here](https://www.browserstack.com/accounts/settings)
+
+- Replace `bs://<app-id>` wkth the URL obtained from app upload step
+
+- Set the device and OS version
+
+- If you have uploaded your own app update the test case
+
+- Run `ruby browserstack_sample.rb`
+
+- You can access the test execution results, and debugging information such as video recording, network logs on [App Automate dashboard](https://app-automate.browserstack.com/dashboard)
+
+---
+
+### Use Local testing for apps that access resources hosted in development or testing environments :
+
+**1. Upload your Android or iOS App**
+
+Upload your Android app (.apk or .aab file) or iOS app (.ipa file) that access resources hosted on your internal or test environments to BrowserStack servers using our REST API. Here is an example cURL request :
+
+```
+curl -u "YOUR_USERNAME:YOUR_ACCESS_KEY" \
+-X POST "https://api-cloud.browserstack.com/app-automate/upload" \
+-F "file=@/path/to/apk/file"
+```
+
+Ensure that @ symbol is prepended to the file path in the above request. Please note the `app_url` value returned in the API response. We will use this to set the application under test while configuring the test later on.
+
+**Note**: If you do not have an .apk or .ipa file and are looking to simply try App Automate, you can download and test using our [sample Android Local app](https://www.browserstack.com/app-automate/sample-apps/android/LocalSample.apk) or [sample iOS Local app](https://www.browserstack.com/app-automate/sample-apps/ios/LocalSample.ipa).
+
+
+**2. Configure and run your local test**
+
+Open `browserstack_sample_local.rb` file in `android` or `ios` directory :
+
+- Replace `YOUR_USERNAME` & `YOUR_ACCESS_KEY` with your BrowserStack access credentials. Get your BrowserStack access credentials from [here](https://www.browserstack.com/accounts/settings)
+
+- Replace `bs://<app-id>` wkth the URL obtained from app upload step
+
+- Set the device and OS version
+
+- Ensure that `browserstack.local` capability is set to `true`. Within the test script, there is code snippet that automatically establishes Local Testing connection to BrowserStack servers using Ruby binding for BrowserStack Local. 
+
+- If you have uploaded your own app update the test case
+
+- Run `ruby browserstack_sample_local.rb`
+
+- You can access the test execution results, and debugging information such as video recording, network logs on [App Automate dashboard](https://app-automate.browserstack.com/dashboard)
+
+## Integration with other frameworks
+
+For other Ruby frameworks samples, refer to following repositories :
 
 - [Cucumber](https://github.com/browserstack/cucumber-ruby-appium-app-browserstack)
+
+Note: For other test frameworks supported by App-Automate refer our [Developer documentation](https://www.browserstack.com/docs/)
+
+## Getting Help
+
+If you are running into any issues or have any queries, please check [Browserstack Support page](https://www.browserstack.com/support/app-automate) or [get in touch with us](https://www.browserstack.com/contact?ref=help).
diff --git a/android/README.md b/android/README.md
deleted file mode 100644
index 2af07eb..0000000
--- a/android/README.md
+++ /dev/null
@@ -1,28 +0,0 @@
-## Android
-
-## Prerequisites
-- Install the appium_lib gem<br>
-`gem install 'appium_lib'`
-- Install the local bindings gem (if you need to run local tests)<br>
-`gem install 'browserstack-local'`
-
-## Running your tests
-- Do remember to switch the USERNAME and ACCESS_KEY with your own browserstack credentials.
-- Upload your Native App (.apk file) to BrowserStack servers using upload API:
-
-  ```
-  curl -u "username:accesskey" -X POST "https://api.browserstack.com/app-automate/upload" -F "file=@/path/to/app/file/Application-debug.apk"
-  ```
-
-- If you do not have an .apk file and looking to simply try App Automate, you can download our [sample app](https://www.browserstack.com/app-automate/sample-apps/android/WikipediaSample.apk)
-and upload to the BrowserStack servers using the above API.
-- For running local tests, you can use our [local sample app](https://www.browserstack.com/app-automate/sample-apps/android/LocalSample.apk).
-- Update the desired capability "app" with the App URL returned from the above API call
-
-## Notes
-* You can view your test results on the [BrowserStack App Automate dashboard](https://www.browserstack.com/app-automate)
-* Refer [Get Started](https://www.browserstack.com/app-automate/appium-ruby) document to configure the capabilities
-
-For frameworks integration with BrowserStack, refer to their individual repositories -
-
-- [Cucumber](https://github.com/browserstack/cucumber-ruby-appium-app-browserstack)
diff --git a/android/single_test.rb b/android/browserstack_sample.rb
similarity index 51%
rename from android/single_test.rb
rename to android/browserstack_sample.rb
index 9440c1b..b141545 100644
--- a/android/single_test.rb
+++ b/android/browserstack_sample.rb
@@ -1,25 +1,38 @@
-require 'rubygems'
+Derequire 'rubygems'
 require 'appium_lib'
 require 'selenium-webdriver'
 
-username = 'BROWSERSTACK_USERNAME'
-access_key = 'BROWSERSTACK_ACCESS_KEY'
-
 caps = {}
-caps['build'] = 'Ruby Appium Sample'
+# Set your access credentials
+caps['browserstack.user'] = 'ysmnturut_aqNVOR'
+caps['browserstack.key'] = 'n8WqPYcXQNBwiDmi8K8H'
+
+# Set URL of the application under test
+caps['app'] = 'bs://<app-id>'
+
+# Specify device and os_version for testing
+caps['device'] = 'Google Pixel 3'
+caps['os_version'] = '9.0'
+
+# Set other BrowserStack capabilities
+caps['project'] = 'First Ruby project'
+caps['build'] = 'browserstack-build-1'
 caps['name'] = 'single_test'
-caps['device'] = 'Google Pixel'
+
+#Set the platform name
 caps['platformName'] = 'android'
-caps['browserstack.debug'] = true
-caps['app'] = 'bs://<hashed app-id>'
 
+# Initialize the remote Webdriver using BrowserStack remote URL
+# and desired capabilities defined above
 appium_driver = Appium::Driver.new({
 	'caps' => caps,
 	'appium_lib' => {
-		:server_url => "http://#{username}:#{access_key}@hub-cloud.browserstack.com/wd/hub"
+		:server_url => "http://hub-cloud.browserstack.com/wd/hub"
 	}}, true)
 driver = appium_driver.start_driver
 
+# Test case for the BrowserStack sample Android app. 
+# If you have uploaded your app, update the test case here. 
 wait = Selenium::WebDriver::Wait.new(:timeout => 30)
 wait.until { driver.find_element(:accessibility_id, "Search Wikipedia").displayed? }
 element = driver.find_element(:accessibility_id, "Search Wikipedia")
@@ -37,4 +50,5 @@
 	puts "No results found - Test Failed"
 end
 
+# Invoke driver.quit() after the test is done to indicate that the test is completed.
 driver.quit
diff --git a/android/local_test.rb b/android/browserstack_sample_local.rb
similarity index 53%
rename from android/local_test.rb
rename to android/browserstack_sample_local.rb
index 33824df..861aae5 100644
--- a/android/local_test.rb
+++ b/android/browserstack_sample_local.rb
@@ -3,29 +3,47 @@
 require 'selenium-webdriver'
 require 'browserstack/local'
 
-username = 'BROWSERSTACK_USERNAME'
-access_key = 'BROWSERSTACK_ACCESS_KEY'
+username = 'YOUR_USERNAME'
+access_key = 'YOUR_ACCESS_KEY'
 
 caps = {}
-caps['build'] = 'Ruby Appium Sample'
+# Set your access credentials
+caps['browserstack.user'] = username
+caps['browserstack.key'] = access_key
+
+# Set URL of the application under test
+caps['app'] = 'bs://<app-id>'
+
+# Specify device and os_version for testing
+caps['device'] = 'Google Pixel 3'
+caps['os_version'] = '9.0'
+
+# Set browserstack.local capability as true
+caps['browserstack.local'] = true
+
+# Set other BrowserStack capabilities
+caps['project'] = 'First Ruby project'
+caps['build'] = 'browserstack-build-1'
 caps['name'] = 'local_test'
-caps['device'] = 'Google Pixel'
 caps['platformName'] = 'android'
-caps['browserstack.local'] = true
 caps['browserstack.debug'] = true
-caps['app'] = 'bs://<hashed app-id>'
 
+# Start browserstack local
 bs_local = BrowserStack::Local.new
 bs_local_args = { "key" => access_key }
 bs_local.start(bs_local_args)
 
+# Initialize the remote Webdriver using BrowserStack remote URL
+# and desired capabilities defined above
 appium_driver = Appium::Driver.new({
 	'caps' => caps,
 	'appium_lib' => {
-		:server_url => "http://#{username}:#{access_key}@hub-cloud.browserstack.com/wd/hub"
+		:server_url => "http://hub-cloud.browserstack.com/wd/hub"
 	}}, true)
 driver = appium_driver.start_driver
 
+# Test case for the BrowserStack sample Android app. 
+# If you have uploaded your app, update the test case here. 
 wait = Selenium::WebDriver::Wait.new(:timeout => 30)
 wait.until { driver.find_element(:id, "com.example.android.basicnetworking:id/test_action").displayed? }
 element = driver.find_element(:id, "com.example.android.basicnetworking:id/test_action")
@@ -40,5 +58,7 @@
   puts "Local Testing setup not working - Test Failed"
 end
 
+# Invoke driver.quit() after the test is done to indicate that the test is completed.
 driver.quit
+# Stop browserstack local
 bs_local.stop
diff --git a/ios/README.md b/ios/README.md
deleted file mode 100644
index 7626bac..0000000
--- a/ios/README.md
+++ /dev/null
@@ -1,28 +0,0 @@
-## iOS
-
-## Prerequisites
-- Install the appium_lib gem<br>
-`gem install 'appium_lib'`
-- Install the local bindings gem (if you need to run local tests)<br>
-`gem install 'browserstack-local'`
-
-## Running your tests
-- Do remember to switch the USERNAME and ACCESS_KEY with your own browserstack credentials.
-- Upload your Native App (.ipa file) to BrowserStack servers using upload API:
-
-  ```
-  curl -u "username:accesskey" -X POST "https://api.browserstack.com/app-automate/upload" -F "file=@/path/to/app/file/Application-debug.ipa"
-  ```
-
-- If you do not have an .ipa file and looking to simply try App Automate, you can download our [sample app](https://www.browserstack.com/app-automate/sample-apps/ios/BStackSampleApp.ipa)
-and upload to the BrowserStack servers using the above API.
-- For running local tests, you can use our [local sample app](https://www.browserstack.com/app-automate/sample-apps/ios/LocalSample.ipa).
-- Update the desired capability "app" with the App URL returned from the above API call
-
-## Notes
-* You can view your test results on the [BrowserStack App Automate dashboard](https://www.browserstack.com/app-automate)
-* Refer [Get Started](https://www.browserstack.com/app-automate/appium-ruby) document to configure the capabilities
-
-For frameworks integration with BrowserStack, refer to their individual repositories -
-
-- [Cucumber](https://github.com/browserstack/cucumber-ruby-appium-app-browserstack)
diff --git a/ios/single_test.rb b/ios/browserstack_sample.rb
similarity index 54%
rename from ios/single_test.rb
rename to ios/browserstack_sample.rb
index 0b1d409..152d65d 100644
--- a/ios/single_test.rb
+++ b/ios/browserstack_sample.rb
@@ -2,24 +2,37 @@
 require 'appium_lib'
 require 'selenium-webdriver'
 
-username = 'BROWSERSTACK_USERNAME'
-access_key = 'BROWSERSTACK_ACCESS_KEY'
-
 caps = {}
-caps['build'] = 'Ruby Appium Sample'
+# Set your access credentials
+caps['browserstack.user'] = 'YOUR_USERNAME'
+caps['browserstack.key'] = 'YOUR_ACCESS_KEY'
+
+# Set URL of the application under test
+caps['app'] = 'bs://<app-id>'
+
+# Specify device and os_version for testing
+caps['device'] = "iPhone 11 Pro"
+caps['os_version'] = "13"
+
+# Set other BrowserStack capabilities
+caps['project'] = 'First Ruby project'
+caps['build'] = 'browserstack-build-1'
 caps['name'] = 'single_test'
-caps['device'] = 'iPhone 7 Plus'
+
+#Set the platform name
 caps['platformName'] = 'iOS'
-caps['browserstack.debug'] = true
-caps['app'] = 'bs://<hashed app-id>'
 
+# Initialize the remote Webdriver using BrowserStack remote URL
+# and desired capabilities defined above
 appium_driver = Appium::Driver.new({
 	'caps' => caps,
 	'appium_lib' => {
-		:server_url => "http://#{username}:#{access_key}@hub-cloud.browserstack.com/wd/hub"
+		:server_url => "http://hub-cloud.browserstack.com/wd/hub"
 	}}, true)
 driver = appium_driver.start_driver
 
+# Test case for the BrowserStack sample iOS app. 
+# If you have uploaded your app, update the test case here. 
 wait = Selenium::WebDriver::Wait.new(:timeout => 30)
 wait.until { driver.find_element(:accessibility_id, "Text Button").displayed? }
 textButton = driver.find_element(:accessibility_id, "Text Button")
@@ -40,4 +53,5 @@
   puts "Test Failed"
 end
 
+# Invoke driver.quit() after the test is done to indicate that the test is completed.
 driver.quit
\ No newline at end of file
diff --git a/ios/local_test.rb b/ios/browserstack_sample_local.rb
similarity index 51%
rename from ios/local_test.rb
rename to ios/browserstack_sample_local.rb
index b8fe44b..26c8fb1 100644
--- a/ios/local_test.rb
+++ b/ios/browserstack_sample_local.rb
@@ -3,29 +3,48 @@
 require 'selenium-webdriver'
 require 'browserstack/local'
 
-username = 'BROWSERSTACK_USERNAME'
-access_key = 'BROWSERSTACK_ACCESS_KEY'
+
+username = 'YOUR_USERNAME'
+access_key = 'YOUR_ACCESS_KEY'
 
 caps = {}
-caps['build'] = 'Ruby Appium Sample'
+# Set your access credentials
+caps['browserstack.user'] = username
+caps['browserstack.key'] = access_key
+
+# Set URL of the application under test
+caps['app'] = 'bs://<app-id>'
+
+# Specify device and os_version for testing
+caps['device'] = "iPhone 11 Pro"
+caps['os_version'] = "13"
+
+# Set browserstack.local capability as true
+caps['browserstack.local'] = true
+
+# Set other BrowserStack capabilities
+caps['project'] = 'First Ruby project'
+caps['build'] = 'browserstack-build-1'
 caps['name'] = 'local_test'
-caps['device'] = 'iPhone 7 Plus'
 caps['platformName'] = 'iOS'
-caps['browserstack.local'] = true
 caps['browserstack.debug'] = true
-caps['app'] = 'bs://<hashed app-id>'
 
+# Start browserstack local
 bs_local = BrowserStack::Local.new
 bs_local_args = { "key" => access_key }
 bs_local.start(bs_local_args)
 
+# Initialize the remote Webdriver using BrowserStack remote URL
+# and desired capabilities defined above
 appium_driver = Appium::Driver.new({
   'caps' => caps,
   'appium_lib' => {
-    :server_url => "http://#{username}:#{access_key}@hub-cloud.browserstack.com/wd/hub"
+    :server_url => "http://hub-cloud.browserstack.com/wd/hub"
   }}, true)
 driver = appium_driver.start_driver
 
+# Initialize the remote Webdriver using BrowserStack remote URL
+# and desired capabilities defined above
 wait = Selenium::WebDriver::Wait.new(:timeout => 30)
 wait.until { driver.find_element(:accessibility_id, "TestBrowserStackLocal").displayed? }
 test_button = driver.find_element(:accessibility_id, "TestBrowserStackLocal")
@@ -38,11 +57,14 @@
 
 result_element = driver.find_element(:accessibility_id, "ResultBrowserStackLocal")
 
-if result_element.text.match("Up and running")
+if result_element.text.match('Up and running')
   puts "Test Passed"
 else
   puts "Test Failed"
 end
 
+# Invoke driver.quit() after the test is done to indicate that the test is completed.
 driver.quit
+
+# Stop browserstack local
 bs_local.stop