diff --git a/docs/en/about-appium/appium-clients.md b/docs/en/about-appium/appium-clients.md
index ec15cc9c1d8..e6467849f58 100644
--- a/docs/en/about-appium/appium-clients.md
+++ b/docs/en/about-appium/appium-clients.md
@@ -1,10 +1,10 @@
## List of client libraries with Appium server support
-These libraries wrap standard Selenium client libraries to provide all the regular selenium commands dictated by the [jsonWire protocol](https://code.google.com/p/selenium/wiki/JsonWireProtocol), and add extra commands related to controlling mobile devices, such as **MultiTouch gestures** and **screen orientation**.
+These libraries wrap standard Selenium client libraries to provide all the regular selenium commands dictated by the [JSON Wire protocol](https://code.google.com/p/selenium/wiki/JsonWireProtocol), and add extra commands related to controlling mobile devices, such as **multi-touch gestures** and **screen orientation**.
-Appium client libraries implement the [Mobile JsonWire Protocol](https://code.google.com/p/selenium/source/browse/spec-draft.md?repo=mobile), and the [W3C Webdriver spec](https://dvcs.w3.org/hg/webdriver/raw-file/default/webdriver-spec.html).
+Appium client libraries implement the [Mobile JSON Wire Protocol](https://code.google.com/p/selenium/source/browse/spec-draft.md?repo=mobile) (an official draft extension to the standard protocol), and elements of the [W3C Webdriver spec](https://dvcs.w3.org/hg/webdriver/raw-file/default/webdriver-spec.html) (a transport-agnostic automation spec; this is where the MultiAction API is defined).
-Appium client libraries only **add** functionality, so they can still be used to run regular Selenium sessions.
+The Appium server itself defines custom extensions to the official protocols, giving Appium users helpful access to various device behaviors (such as installing/uninstalling apps during the course of a test session). This is why we need Appium-specific clients, not just the 'vanilla' Selenium clients. Of course, Appium client libraries only **add** functionality (in fact, they simply extend the standard Selenium clients), so they can still be used to run regular Selenium sessions.
Language/Framework | Github Repo and Installation Instructions |
----- | ----- |
diff --git a/docs/en/about-appium/intro.md b/docs/en/about-appium/intro.md
index f93146654c5..87426b8a60f 100644
--- a/docs/en/about-appium/intro.md
+++ b/docs/en/about-appium/intro.md
@@ -95,7 +95,7 @@ Appium is a server written in Node.js. It can be built and installed from source
There are client libraries (in Java, Ruby, Python, PHP, JavaScript, and C#)
which support Appium's extensions to the WebDriver protocol. When using Appium,
you want to use these client libraries instead of your regular WebDriver
-client. You can view the full list of libraries [here](/appium-clients.md).
+client. You can view the full list of libraries [here](appium-clients.md).
**[Appium.app](https://github.com/appium/appium-dot-app), [Appium.exe](https://github.com/appium/appium-dot-exe)**
There exist GUI wrappers around the Appium server that can be downloaded.
diff --git a/docs/en/advanced-concepts/grid.md b/docs/en/advanced-concepts/grid.md
index b832996746c..ccaeee5d08d 100644
--- a/docs/en/advanced-concepts/grid.md
+++ b/docs/en/advanced-concepts/grid.md
@@ -1,10 +1,12 @@
## Selenium Grid
-You are able to register your appium server with a local grid by using the
+You are able to register your appium server with a local [Selenium grid](https://code.google.com/p/selenium/wiki/Grid2) by using the
`--nodeconfig` server parameter.
```bash
-> node . -V --nodeconfig /path/to/nodeconfig.json
+> appium --nodeconfig /path/to/nodeconfig.json
+# or, if running from source:
+> node . --nodeconfig /path/to/nodeconfig.json
```
In the node config file you have to define the `browserName`,
diff --git a/docs/en/advanced-concepts/hybrid.md b/docs/en/advanced-concepts/hybrid.md
index b2fda29a9b0..2b96fafbe84 100644
--- a/docs/en/advanced-concepts/hybrid.md
+++ b/docs/en/advanced-concepts/hybrid.md
@@ -46,7 +46,7 @@ driver
```java
// java
-// assuming we have an initialized `driver` object for an app
+// assuming we have a set of capabilities
driver = new AppiumDriver(new URL("http://127.0.0.1:4723/wd/hub"), capabilities);
Set contextNames = driver.getContextHandles();
@@ -67,7 +67,7 @@ driver.quit();
```ruby
# ruby
-# assuming we have an initialized `driver` object for an app
+# assuming we have a set of capabilities
@driver = Selenium::WebDriver.for(:remote, :desired_capabilities => capabilities, :url => SERVER_URL)
# I switch to the last window because its always the webview in our case, in other cases you may need to specify a window number
@@ -123,7 +123,7 @@ public function testThings()
$contexts = $this->contexts();
$this->assertEquals($expected_contexts, $contexts);
- $this->context('WEBVIEW_1');
+ $this->context($contexts[1]);
$context = $this->context();
$this->assertEquals('WEBVIEW_1', $context);
diff --git a/docs/en/appium-setup/android-hax-emulator.md b/docs/en/appium-setup/android-hax-emulator.md
index 3c596944280..cbd9c2aa382 100644
--- a/docs/en/appium-setup/android-hax-emulator.md
+++ b/docs/en/appium-setup/android-hax-emulator.md
@@ -1,7 +1,7 @@
## Intel® Hardware Accelerated Execution Manager
If you find the android emulator a slow and your system runs on an Intel®
-cpu, you can check out HAXM. HAXM let's you leverage your hardware for
+cpu, you can check out HAXM. HAXM lets you leverage your hardware for
virtualization, accelerating the emulator.
* To install HAXM open the Android SDK Manager, you will find the package
@@ -9,6 +9,6 @@ virtualization, accelerating the emulator.
* You can find all relevant documentation on [Intel's website][1]
* This will require an x86 emulator image
* Use Intel's package to install HAXM; The Android SDK Manager appears to not
- do so successfully.
+ do so successfully, depending on the version you might have installed
[1]: http://software.intel.com/en-us/articles/intel-hardware-accelerated-execution-manager/
diff --git a/docs/en/appium-setup/real-devices.md b/docs/en/appium-setup/real-devices.md
index a2df66de981..c60b45513ef 100644
--- a/docs/en/appium-setup/real-devices.md
+++ b/docs/en/appium-setup/real-devices.md
@@ -19,7 +19,7 @@ necessary to test on a real device. Your app will also need to be signed. You
can find information about this in the [Apple documentation](https://developer.apple.com/library/ios/documentation/IDEs/Conceptual/AppDistributionGuide/TestingYouriOSApp/TestingYouriOSApp.html).
Appium will attempt to install your app using Fruitstrap, but it is often easier
-to pre-install your app using Xcode to ensure there are no problems.
+to pre-install your app using Xcode to ensure there are no problems (see the [iOS deploy](ios-deploy.md) doc for more information).
### Running your tests with Appium
@@ -65,4 +65,6 @@ the capabilities that you can use.
Hooray! There's nothing extra to know about testing real Android devices: it
works exactly the same as testing on emulators. Make sure that your device
-can connect to ADB and has Developer Mode enabled.
+can connect to ADB and has Developer Mode enabled. For testing Chrome on a real
+device, you're responsible for ensuring that Chrome of an appropriate version
+is installed.
diff --git a/docs/en/appium-setup/running-on-linux.md b/docs/en/appium-setup/running-on-linux.md
index 2d2d25fc42b..8679212436b 100644
--- a/docs/en/appium-setup/running-on-linux.md
+++ b/docs/en/appium-setup/running-on-linux.md
@@ -28,17 +28,16 @@ Appium checkout to install all the dependencies.
### Running Appium
To run tests on Linux, you will need to have the Android Emulator booted and
-running an AVD with API Level 17 or greater. Then run Appium on the command
-line using node.js:
-
- node .
+running an AVD with API Level 17 or greater. Then run Appium (`appium`) after
+installing via NPM, or `node .` in the source directory if running from source.
See the [server documentation](server-args.md) for all the command line
arguments.
### Notes
-* There exists a hardware accelerated emulator for android, it has it's own
+* There exists a hardware accelerated emulator for android, it has its own
limitations. For more information you can check out this
[page](android-hax-emulator.md).
-* Make sure that `hw.battery=yes` in your AVD's `config.ini`.
+* Make sure that `hw.battery=yes` in your AVD's `config.ini`, if you want to
+ run any of the Appium tests
diff --git a/docs/en/appium-setup/running-on-osx.md b/docs/en/appium-setup/running-on-osx.md
index 2e22bf38c73..d1811b3a57f 100644
--- a/docs/en/appium-setup/running-on-osx.md
+++ b/docs/en/appium-setup/running-on-osx.md
@@ -4,11 +4,11 @@ Appium on OS X supports iOS and Android testing.
### System setup (iOS)
-* Appium requires Mac OS X 10.7, but 10.8 is recommended.
+* Appium requires Mac OS X 10.7, but 10.8 or 10.9 is recommended.
* Make sure you have Xcode and the iOS SDK(s) installed. (Appium currently
- supports Xcode 4.6.3 for iOS up to 6.1 and Xcode 5 for iOS 7.0 and 7.1. Note
- that testing against iOS versions below 7.0 using Xcode 5 is not recommended.
- See the next section for more information.)
+ supports Xcode 4.6.3 for iOS up to 6.1 and Xcode 5.x for iOS 7.0 and 7.1.
+ Note that testing against iOS versions below 7.0 using Xcode 5 is not
+ recommended. See the next section for more information.)
* You need to authorize use of the iOS Simulator. If you are running Appium
from NPM, you'll do this by running `sudo authorize_ios` (`authorize_ios` is
a binary made available by the Appium npm package). If you're running Appium