Simplify guide and make it more prescriptive

Summary:
This is related to #8157. Updated the guide and made it simpler and more prescriptive.

**Testing**

- cd react-native
- npm install
- cd website
- npm install
- npm start
- Go to http://localhost:8079/react-native/docs/platform-specific-code.html
- Checked content

![platform-specific-update](https://cloud.githubusercontent.com/assets/691109/16205926/f5fd0662-36da-11e6-978c-e364688facf6.png)
Closes https://github.com/facebook/react-native/pull/8251

Differential Revision: D3458249

Pulled By: JoelMarcey

fbshipit-source-id: 5568337af92da53ee6cd53541591eb01ae323f4f

docs/PlatformSpecificInformation.md

@@ -7,34 +7,12 @@ permalink: docs/platform-specific-code.html
 next: native-modules-ios
 ---
 
-When building a cross-platform app, the need to write different code for different platforms may arise. This can always be achieved by organizing the various components in different folders:
+When building a cross-platform app, you'll want to re-use as much code as possible. Scenarios may arise where it makes sense for the code to be different, for example you may want to implement separate visual components for iOS and Android.
 
-```sh
-/common/components/
-/android/components/
-/ios/components/
-```
+React Native provides two ways to easily organize your code and separate it by platform:
 
-Another option may be naming the components differently depending on the platform they are going to be used in:
-
-```sh
-BigButtonIOS.js
-BigButtonAndroid.js
-```
-
-But React Native provides two alternatives to easily organize your code separating it by platform:
-
-## Platform specific extensions
-React Native will detect when a file has a `.ios.` or `.android.` extension and load the right file for each platform when requiring them from other components.
-
-For example, you can have these files in your project:
-
-```sh
-BigButton.ios.js
-BigButton.android.js
-```
-
-With this setup, you can just require the files from a different component without paying attention to the platform in which the app will run.
+* Using the `Platform` module.
+* Using platform-specific file extensions.
 
 ```javascript
 import BigButton from './components/BigButton';
@@ -43,25 +21,24 @@ import BigButton from './components/BigButton';
 React Native will import the correct component for the running platform.
 
 ## Platform module
-A module is provided by React Native to detect what is the platform in which the app is running. This piece of functionality can be useful when only small parts of a component are platform specific.
+React Native provides a module that detects the platform in which the app is running. You can use the detection logic to implement platform-specific code. Use this option when only small parts of a component are platform-specific.
 
 ```javascript
-var { Platform } = ReactNative;
+import { Platform, StyleSheet } from 'react-native';
 
-var styles = StyleSheet.create({
+const styles = StyleSheet.create({
   height: (Platform.OS === 'ios') ? 200 : 100,
 });
 ```
 
-`Platform.OS` will be `ios` when running in iOS and `android` when running in an Android device or simulator.
+`Platform.OS` will be `ios` when running on iOS and `android` when running on Android.
 
-There is also a `Platform.select` method available, that given an object containing Platform.OS as keys,
-returns the value for the platform you are currently running on.
+There is also a `Platform.select` method available, that given an object containing Platform.OS as keys, returns the value for the platform you are currently running on.
 
 ```javascript
-var { Platform } = ReactNative;
+import { Platform, StyleSheet } from 'react-native';
 
-var styles = StyleSheet.create({
+const styles = StyleSheet.create({
   container: {
     flex: 1,
     ...Platform.select({
@@ -76,13 +53,12 @@ var styles = StyleSheet.create({
 });
 ```
 
-This will result in a container having `flex: 1` on both platforms and backgroundColor - red on iOS and blue
-on Android.
+This will result in a container having `flex: 1` on both platforms, a red background color on iOS, and a blue background color on Android.
 
 Since it accepts `any` value, you can also use it to return platform specific component, like below:
 
 ```javascript
-var Component = Platform.select({
+const Component = Platform.select({
   ios: () => require('ComponentIOS'),
   android: () => require('ComponentAndroid'),
 })();
@@ -90,13 +66,32 @@ var Component = Platform.select({
 <Component />;
 ```
 
-###Detecting Android version
-On Android, the Platform module can be also used to detect which is the version of the Android Platform in which the app is running
+### Detecting the Android version
+
+On Android, the `Platform` module can also be used to detect the version of the Android Platform in which the app is running:
 
 ```javascript
-var {Platform} = ReactNative;
+import { Platform } from 'react-native';
 
 if(Platform.Version === 21){
   console.log('Running on Lollipop!');
 }
 ```
+
+## Platform-specific extensions
+When your platform-specific code is more complex, you should consider splitting the code out into separate files. React Native will detect when a file has a `.ios.` or `.android.` extension and load the relevant platform file when required from other components.
+
+For example, say you have the following files in your project:
+
+```sh
+BigButton.ios.js
+BigButton.android.js
+```
+
+You can then require the component as follows:
+
+```javascript
+const BigButton = require('./BigButton');
+```
+
+React Native will automatically pick up the right file based on the running platform.