some doc updates

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 |
 ----- | ----- |

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)**<br/>
 There exist GUI wrappers around the Appium server that can be downloaded.

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`,

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<String> 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);
 

docs/en/appium-setup/android-hax-emulator.md

@@ -1,14 +1,14 @@
 ## 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
   under Extras.
 * 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/

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.

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

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