tawasuyu/taffy

diff --git a/README.md b/README.md
index ee97f7de5..07d66f685 100644
--- a/README.md
+++ b/README.md
@@ -17,8 +17,128 @@ Before using or contributing to stretch it is good to be aware of the core goals
 - Multi-threaded layout
 - Language bindings for most common languages
 
+## Supported Platforms
+
+- Rust
+- Android
+- iOS
+- JavaScript / TypeScript
+
 ## Usage
-Stretch is still in its initial development phase so we currently don't publish any artifacts to package managers. If you want to use stretch today or start contributing to the development of stretch you will need to build it locally.
+Stretch is built in rust but comes with bindings to multiple languages and platforms so you can use it in a way that feels natural to your project.
+
+### Rust
+```toml
+# Cargo.toml
+
+[dependencies]
+stretch = "0.2.2"
+```
+
+```rust
+// main.rs
+
+use stretch::style::*;
+use stretch::node::*;
+use stretch::result::*;
+
+fn main() {
+  let node = Node::new(
+      Style {
+          size: Size { width: Dimension::Points(100.0), height: Dimension::Points(100.0) },
+          justify_content: JustifyContent::Center,
+          ..Default::default()
+      },
+      vec![&Node::new(
+          Style { size: Size { width: Dimension::Percent(0.5), height: Dimension::Auto }, ..Default::default() },
+          vec![],
+      )],
+  );
+
+  let layout = node.compute_layout(Size::undefined()).unwrap();
+  dbg!(layout);
+}
+```
+
+### Android
+```groovy
+// Build.gradle
+
+android {
+    splits {
+        abi {
+            enable true
+        }
+    }
+}
+
+dependencies {
+    implementation 'app.visly.stretch:stretch:0.2.2'
+}
+```
+
+```kotlin
+// MainActivity.kt
+
+val node = Node(
+  Style(size = Size(Dimension.Points(100f), Dimension.Points(100f))), 
+  listOf(
+    Node(Style(size = Size(Dimension.Percent(0.5f), Dimension.Percent(0.5f))), listOf())
+  ))
+
+val layout = node.computeLayout(Size(null, null))
+Log.d(TAG, "width: ${width}, height: ${height}")
+```
+
+### iOS
+```ruby
+# Podfile
+
+pod 'StretchKit', '~> 0.2.2'
+```
+
+```swift
+// ViewController.swift
+ 
+let node = Node(
+  style: Style(size: Size(width: .points(100.0), height: .points(100.0)), justifyContent: .center), 
+  children: [
+    Node(style: Style(size: Size(width: .percent(0.5), height: .percent(0.5))), children: [])
+  ])
+  
+let layout = node.computeLayout(thatFits: Size(width: nil, height: nil))
+print("width: \(layout.width), height: \(layout.height)")
+```
+
+### JavaScript
+```bash
+> npm install --save stretch-layout
+```
+
+```javascript
+// index.js
+
+import { Node, JustifyContent } from 'stretch-layout';
+
+const node = new Node({width: 100, height: 100, justifyContent: JustifyContent.Center});
+node.addChild(new Node({width: '50%', height: '50%'}));
+const layout = node.computeLayout();
+
+console.log(layout.width, layout.height);
+```
+
+## Contributing
+Contributions are very welcome. Though we ask that you open an issue or pull request early in the process (before writing code) so we can discuss solutions and additions before you start spending time on implementing them. There are some specific areas where we would be extra happy to receive contributions in.
+
+- Binary size reduction
+- Runtime performance
+- Ensure build / test environment works well on non macOS platforms
+- Alternate layout systems (grid layout perhaps?)
+- Web compatibility tests
+- RTL support
+- Platform bindings
+- API improvements
+- Documentation & Examples
 
 ### Installation
 If you don't have rust installed you have to do that first as well as install some components that we make use of to format and lint the codebase. For more on rust see their [website](https://www.rust-lang.org).
@@ -37,6 +157,8 @@ cd stretch
 cargo test
 ```
 
+If you have made any changes to the API you should also udpate and run tests for all the platform bindings located in `/bindings/*`.
+
 ### Testing
 Stretch is tested by validating that layouts written in stretch perform the same as in Chrome. This is done by rendering an equivalent layout in HTML and then generating a rust test case which asserts that the resulting layout is the same when run through stretch.
 
@@ -51,16 +173,8 @@ Once you have chromedriver installed and available in `PATH` you can re-generate
 
 To add a new test case add another HTML file to `/test_fixtures` following the current tests as a template for new tests.
 
-## Contributing
-Contributions are very welcome. Though we ask that you open an issue or pull request early in the process (before writing code) so we can discuss solutions and additions before you start spending time on implementing them. There are some specific areas where we would be extra happy to receive contributions in.
-
-- Binary size reduction
-- Runtime performance
-- Ensure build / test environment works well on non macOS platforms
-- Alternate layout systems (grid layout perhaps?)
-- Web compatibility tests
-- RTL support
-- Platform bindings
+### Benchmarking
+Benchmarks build on the same infrastructure as testing, and actually benchmarks are automatically generated from test fixtures just like tests. Run `cargo bench` to run benchmarks locally.
 
 ## Relationship to Yoga
 [Yoga](https://www.yogalayout.com) is a cross-platform implementation of Flexbox written in C. Yoga is a fantastic project but has some fundamental issues which we hope to resolve. Compared to Yoga we aim to have a stronger adherence to web standards, a flexible architecture eventually supporting multiple layout algorithms, and future performance improvements including multi-threaded layout. In addition to this we aim to use a safer language with a more modern codebase.