add intro and platform-support docs

README.md

@@ -13,12 +13,15 @@ description: Want to rock your mobile app automation? This is how you get starte
 [![Build Status](https://api.travis-ci.org/appium/appium.png?branch=master)](https://travis-ci.org/appium/appium)
 [![Dependency Status](https://gemnasium.com/appium/appium.png)](https://gemnasium.com/appium/appium)
 
+
 ## Supported Platforms
 
 * iOS
 * Android
 * FirefoxOS
 
+See the [platform support doc](platform-support) for more detailed information.
+
 ## Why Appium?
 
 1. You don't have to recompile your app or modify it in any way, due
@@ -30,14 +33,17 @@ description: Want to rock your mobile app automation? This is how you get starte
    with the Selenium WebDriver API and language-specific client libraries.
 3. You can use any testing framework.
 
-Investing in [WebDriver](https://code.google.com/p/selenium/wiki/JsonWireProtocol) means you are betting
-on a single, free and open protocol for testing that has become a defacto standard. Don't lock yourself into a proprietary stack.
+Investing in the [WebDriver](https://code.google.com/p/selenium/wiki/JsonWireProtocol) protocol means you are betting on a single, free and open protocol for testing that has become a defacto standard. Don't lock yourself into a proprietary stack.
 
 If you use Apple's UIAutomation library without Appium you can only write tests
 using JavaScript and you can only run tests through the Instruments application.
 Similarly, with Google's UiAutomator you can only write tests in Java. Appium
 opens up the possibility of true cross-platform native mobile automation. Finally!
 
+## I don't get it yet...
+
+If you're new to Appium, or want a fuller description of what this is all about, please read our [Introduction to Appium Concepts](intro).
+
 ## Requirements
 
 Your environment needs to be setup for the particular mobile platforms that you

docs/en/intro.md

@@ -0,0 +1,57 @@
+Introduction to Appium
+============
+
+Appium is an open-source tool you can use to automate mobile native, mobile web, and mobile hybrid applications on iOS and Android platforms. "Mobile native apps" are those written using the iOS or Android SDKs. "Mobile web apps" are web apps accessed using a mobile browser (Appium supports Safari on iOS and Chrome on Android). "Mobile hybrid apps" have a native wrapper around a "webview"--a native control that enables interaction with web content. Projects like [Phonegap](http://phonegap.com/), for example, make it easy to build apps using web technologies that are then bundled into a native wrapper---these are hybrid apps.
+
+Importantly, Appium is "cross-platform": it allows you to write tests against multiple platforms (iOS, Android), using the same API. This enables a large or total amount of code reuse between iOS and Android testsuites.
+
+For specific information about what it means for Appium to "support" its platforms, version, and automation modalities, please see the [platform support doc](platform-support).
+
+Appium Philosophy
+-----
+
+Appium was designed to meet mobile automation needs according to a certain philosophy. The key points of this philosophy can be stated as 4 requirements:
+
+1. You shouldn't have to recompile your app or modify it in any way in order to automate it.
+2. You shouldn't be locked into a specific language or framework to write and run your tests.
+3. A mobile automation framework shouldn't reinvent the wheel when it comes to automation APIs.
+4. A mobile automation framework should be open source, in spirit and practice as well as in name!
+
+Appium Design
+------------
+
+So how does the structure of the Appium project live out this philosophy? We meet requirement #1 by using vendor-provided automation frameworks under the hood. That way, we don't need to compile in any Appium-specific or third-party code or frameworks to your app. This means you're testing the same app you're shipping. The vendor-provided frameworks we use are:
+
+* iOS: Apple's [UIAutomation](https://developer.apple.com/library/ios/documentation/DeveloperTools/Reference/UIAutomationRef/_index.html)
+* Android 4.2+: Google's [UiAutomator](http://developer.android.com/tools/help/uiautomator/index.html)
+* Android 2.3+: Google's [Instrumentation](http://developer.android.com/reference/android/app/Instrumentation.html). (Instrumentation support is provided by bundling a separate project, [Selendroid](http://selendroid.io))
+
+We meet requirement #2 by wrapping the vendor-provided frameworks in one API, the [WebDriver](http://docs.seleniumhq.org/projects/webdriver/) API. WebDriver (aka "Selenium WebDriver") specifies a client-server protocol (known as the [JSON Wire Protocol](https://code.google.com/p/selenium/wiki/JsonWireProtocol)). Given this client-server architecture, a client written in any language can be used to send the appropriate HTTP requests to the server. There are already clients written in every popular programming language. This also means that you're free to use whatever test runner and test framework you want; the client libraries are simply HTTP clients and can be mixed into your code any way you please. In other words, Appium & WebDriver clients are not technically "test frameworks"--they are "automation libraries". You can manage your test environment any way you like!
+
+We meet requirement #3 in the same way: WebDriver has become the de facto standard for automating web browsers, and is a [W3C Working Draft](https://dvcs.w3.org/hg/webdriver/raw-file/tip/webdriver-spec.html). Why do something totally different for mobile? Instead we have [extended the protocol](https://code.google.com/p/selenium/source/browse/spec-draft.md?repo=mobile) with extra API methods useful for mobile automation.
+
+It should be obvious that requirement #4 is a given---you're reading this because [Appium is open source](https://github.com/appium/appium).
+
+Appium Concepts
+------
+
+*Client/Server Architecture*
+Appium is at its heart a webserver that exposes a REST API. It receives connections from a client, listens for commands, executes those commands on a mobile device, and responds with an HTTP response representing the result of the command execution. The fact that we have a client/server architecture opens up a lot of possibilities: we can write our test code in any language that has a client. We can put the server on a different machine than our tests are running on. We can write test code and rely on a cloud service like [Sauce Labs](https://saucelabs.com/mobile) to receive and interpret the commands.
+
+*Session*
+Automation is always performed in the context of a session. Clients initiate a session with a server in ways specific to each library, but they all end up sending a `POST /session` request to the server, with a JSON object called the 'desired capabilities' object. At this point the server will start up the automation session and respond with a session ID which can be used in sending further commands.
+
+*Desired Capabilities*
+Desired capabilities are sets of keys and values (i.e., a map or hash) sent to the Appium server to tell the server what kind of automation session we're interested in starting up. There are also various capabilities which can modify the behavior of the server during automation. For example, we might set the `platformName` capability to `iOS` to tell Appium that we want an iOS session, rather than an Android one. Or we might set the `safariAllowPopups` capability to `true` in order to ensure that, during a Safari automation session, we're allowed to use JavaScript to open up new windows. See the [capabilities doc](caps) for the complete list of capabilities available for Appium.
+
+*Appium Server*
+Appium is a server written with Node.js. It can be built and installed from source or directly from NPM.
+
+*Appium.app, Appium.exe*
+There exist GUI wrappers around the Appium server that can be downloaded. These come bundled with everything required to run the Appium server, so you don't need to worry about Node. They also come with an Inspector, which enables you to check out the hierarchy of your app. This can come in very handy when writing tests!
+
+Getting Started
+-----
+
+Congratulations! You are now armed with enough knowledge to begin using Appium. Why not head back to the [getting started doc](getting-started) for more detailed requirements and instructions?
+

docs/en/mobile-web.md

@@ -112,4 +112,4 @@ Then, use desired capabilities like these to run your test in Chrome:
   app: 'chrome'
   , device: 'Android'
 };
-```
+```

docs/en/platform-support.md

@@ -0,0 +1,34 @@
+Appium Platform Support
+======
+
+Appium supports a variety of platforms and testing modalities (native, hybrid, web, real devices, simulators, etc...). This document is designed to make explicit the level of support and requirements for each of these.
+
+iOS Support
+------
+See [Running on OS X: iOS](running-on-osx#ios) for iOS requirements and setup instructions.
+
+* Versions: 6.1, 7.0, and 7.1
+* Devices: iPhone Simulator, iPad Simulator, and real iPhones and iPads
+* Native app support: Yes, with debug version of .app (simulator), or correctly-signed .ipa (real devices). Underlying support is provided by Apple's [UIAutomation](https://developer.apple.com/library/ios/documentation/DeveloperTools/Reference/UIAutomationRef/_index.html) framework.
+* Mobile web support: Yes, via automation of mobile Safari. For real devices, ios-webkit-remote-debugger is required, and automation of native aspects of the Safari interface is not possible. See the [mobile web doc](mobile-web) for instructions.
+* Hybrid support: Yes. For real devices, ios-webkit-remote-debugger is required. See the [hybrid doc](hybrid) for instructions.
+* Support for automating multiple apps in one session: No
+* Support for automating multiple devices simultaneously: No
+* Support for automating vendor-provided or third-party apps: Only vendor-provided apps (Preferences, Maps, etc...), and only on the simulator
+
+Android Support
+------
+See [Running on OS X: Android](running-on-osx#android), [Running on Windows](running-on-windows), or [Running on Linux](running-on-linux) for Android requirements and setup instructions.
+
+* Versions: 2.3 and up
+  * Versions 4.2 and up are supported via Appium's own [UiAutomator](http://developer.android.com/tools/help/uiautomator/index.html) libraries. This is the default automation backend.
+  * Versions 2.3 through 4.3 are supported via Appium's bundled version of [Selendroid](http://selendroid.io), which utilizes [Instrumentation](http://developer.android.com/reference/android/app/Instrumentation.html). Selendroid has a different set of commands than the default Appium (though this is rapidly being minimized) and a different support profile. To access this automation backend, use the `automationName` capability with the value `Selendroid`.
+* Devices: Android emulators and real Android devices
+* Native app support: Yes
+* Mobile web support: Yes (but not when using Selendroid backend). Automation is effected using a bundled [Chromedriver](https://code.google.com/p/selenium/wiki/ChromeDriver) server as a proxy. With 4.2 and 4.3, automation works on official Chrome browser or Chromium only. With 4.4+, automation also works on the built-in "Browser" app. Chrome/Chromium/Browser must already be installed on the device under test. See the [mobile web doc](mobile-web) for instructions.
+* Hybrid support: Yes. See the [hybrid doc](hybrid) for instructions.
+  * With default Appium automation backend: versions 4.4 and up
+  * With Selendroid automation backend: versions 2.3 and up
+* Support for automating multiple apps in one session: Yes (but not when using the Selendroid backend)
+* Support for automating multiple devices simultaneously: Yes, though Appium must be started using different ports for the server parameters `--port`, `--bootstrap-port` (or `--selendroid-port`) and/or `--chromedriver-port`. See the [server args doc](server-args) for more information on these parameters.
+* Support for automating vendor-provided or third-party apps: Yes (but not when using the Selendroid backend)