diff --git a/GIFs/bouncyDemo.gif b/GIFs/bouncyDemo.gif
new file mode 100644
index 0000000..b5ba4a2
Binary files /dev/null and b/GIFs/bouncyDemo.gif differ
diff --git a/GIFs/dribble.gif b/GIFs/dribble.gif
new file mode 100644
index 0000000..8f2da7d
Binary files /dev/null and b/GIFs/dribble.gif differ
diff --git a/README.md b/README.md
index ff4e505..53c264b 100644
--- a/README.md
+++ b/README.md
@@ -1,17 +1,90 @@
 # BouncyPageViewController
 
-[![CI Status](http://img.shields.io/travis/Bohdan Orlov/BouncyPageViewController.svg?style=flat)](https://travis-ci.org/Bohdan Orlov/BouncyPageViewController)
 [![Version](https://img.shields.io/cocoapods/v/BouncyPageViewController.svg?style=flat)](http://cocoapods.org/pods/BouncyPageViewController)
 [![License](https://img.shields.io/cocoapods/l/BouncyPageViewController.svg?style=flat)](http://cocoapods.org/pods/BouncyPageViewController)
 [![Platform](https://img.shields.io/cocoapods/p/BouncyPageViewController.svg?style=flat)](http://cocoapods.org/pods/BouncyPageViewController)
 
+Page view controller with bounce effect inspired by motion design by [Stan Yakushevish](https://dribbble.com/shots/2985170-Healthy).
+ 
+
+| ![](GIFs/dribble.gif) | ![](GIFs/bouncyDemo.gif) |
+| ------------- |-------------|
+
+# Quickstart
+### Create a queue of `UIViewControllers` to display
+```swift
+let pagesQueue: [UIViewController]() = ... // your view controllers here
+```
+### Create a `BouncyPageViewController ` passing initial view controllers
+```swift
+let pageViewController = BouncyPageViewController(initialViewControllers: Array(pagesQueue[0...1]))
+```
+### Assign closures for providing next/pevious view controllers
+```swift
+pageViewController.viewControllerAfterViewController = self.viewControllerAfterViewController
+pageViewController.viewControllerBeforeViewController = self.viewControllerBeforeViewController
+```
+#### Vend the next ViewController from the queue
+```swift
+func viewControllerAfterViewController(prevVC: UIViewController) -> UIViewController? {
+    if let idx = self.pagesQueue.index(of: prevVC), idx + 1 < self.pagesQueue.count {
+        return self.pagesQueue[idx + 1]
+    }
+    return nil
+}
+```
+### Assign a `didScroll` callback closure
+```swift
+pageViewController.didScroll = self.pageViewControllerDidScroll
+```
+#### Update the UI using the `offset` and `progress`
+```swift
+func pageViewControllerDidScroll(pageViewController: BouncyPageViewController, offset: CGFloat, progress: CGFloat) {
+    for vc in pageViewController.visibleControllers() {
+        let vc = (vc as! ViewController)
+        vc.progress = progress
+
+    }
+}
+```
+# Configuration
+#### How much pages overlap eachother, more inset - higher bounce
+```swift
+    public var pageContentInset: CGFloat = 30
+```
+#### How long the bounce animates when you release the page
+```swift
+    public var pageBounceAnimationDuration: TimeInterval = 1
+```
+#### How far you can scroll the last page until it snaps back (half of the page by default)
+```swift
+    public var overscrollBounceMultiplier: CGFloat = 0.5
+```
 ## Example
 
-To run the example project, clone the repo, and run `pod install` from the Example directory first.
+To run the example project, clone the repo, and run as usual.
+
 
+# Installation
 ## Requirements
+iOS 9+
+
+Swift 3
+
+## Carthage
+To use latest release add this to Cartfile:
+
+```ruby
+git "https://github.com/BohdanOrlov/BouncyPageViewController"
+
+```
+Then run in terminal:
 
-## Installation
+```bash
+$ carthage update
+
+```
+## CocoaPods
 
 BouncyPageViewController is available through [CocoaPods](http://cocoapods.org). To install
 it, simply add the following line to your Podfile:
@@ -22,7 +95,7 @@ pod "BouncyPageViewController"
 
 ## Author
 
-Bohdan Orlov, bohdan.orlov@corp.badoo.com
+Bohdan Orlov, bohdan.orlov@gmail.com
 
 ## License