diff --git a/Readme.md b/Readme.md
index 4f7e099d0..009ad5c19 100644
--- a/Readme.md
+++ b/Readme.md
@@ -80,7 +80,7 @@ app.use((ctx, next) => {
 
 ### GeneratorFunction
 
-To use generator functions, you must use a wrapper such as [co](https://github.com/tj/co) that is no longer supplied with Koa.
+To use generator functions, you must use a wrapper such as [co](https://github.com/tj/co).
 
 ```js
 app.use(co.wrap(function *(ctx, next) {
@@ -91,35 +91,13 @@ app.use(co.wrap(function *(ctx, next) {
 }));
 ```
 
-### Old signature middleware (v1.x) - Deprecated
+### KOA v1.x Middleware Signature
 
-**Old signature middleware (v1.x) support will be removed in v3**
+The middleware signature changed between v1.x and v2.x.  The older signature is deprecated.
 
-Koa v2.x will try to convert legacy signature, generator middleware on `app.use`, using [koa-convert](https://github.com/koajs/convert).
-It is however recommended that you choose to migrate all v1.x middleware as soon as possible.
+**Old signature middleware support will be removed in v3**
 
-```js
-// Koa will convert
-app.use(function *(next) {
-  const start = new Date();
-  yield next;
-  const ms = new Date() - start;
-  console.log(`${this.method} ${this.url} - ${ms}ms`);
-});
-```
-
-You could do it manually as well, in which case Koa will not convert.
-
-```js
-const convert = require('koa-convert');
-
-app.use(convert(function *(next) {
-  const start = new Date();
-  yield next;
-  const ms = new Date() - start;
-  console.log(`${this.method} ${this.url} - ${ms}ms`);
-}));
-```
+Please see the [Migration Guide](docs/migration.md) for more information on upgrading from v1.x.
 
 ## Babel setup
 
diff --git a/docs/migration.md b/docs/migration.md
new file mode 100644
index 000000000..e144d5a3c
--- /dev/null
+++ b/docs/migration.md
@@ -0,0 +1,115 @@
+# Migrating from Koa v1.x to v2.x
+
+## New Middleware Signature 
+
+Koa v2 introduces a new signature for middleware.
+
+**Old signature middleware (v1.x) support will be removed in v3**
+
+The new middleware signature is:
+
+```js
+// uses async arrow functions
+app.use(async (ctx, next) => {
+  try {
+    await next() // next is now a function
+  } catch (err) {
+    ctx.body = { message: err.message }
+    ctx.status = err.status || 500
+  }
+})
+
+app.use(async ctx => {
+  const user = await User.getById(this.session.userid) // await instead of yield
+  ctx.body = user // ctx instead of this
+})
+```
+
+You don't have to use asynchronous functions - you just have to pass a function that returns a promise. 
+A regular function that returns a promise works too!
+
+The signature has changed to pass `Context` via an explicit parameter, `ctx` above, instead of via
+`this`.  The context passing change makes koa more compatible with es6 arrow functions, which capture `this`.
+
+## Using v1.x Middleware in v2.x
+
+Koa v2.x will try to convert legacy signature, generator middleware on `app.use`, using [koa-convert](https://github.com/koajs/convert).
+It is however recommended that you choose to migrate all v1.x middleware as soon as possible.
+
+```js
+// Koa will convert
+app.use(function *(next) {
+  const start = new Date();
+  yield next;
+  const ms = new Date() - start;
+  console.log(`${this.method} ${this.url} - ${ms}ms`);
+});
+```
+
+You could do it manually as well, in which case Koa will not convert.
+
+```js
+const convert = require('koa-convert');
+
+app.use(convert(function *(next) {
+  const start = new Date();
+  yield next;
+  const ms = new Date() - start;
+  console.log(`${this.method} ${this.url} - ${ms}ms`);
+}));
+```
+
+## Upgrading Middleware
+
+You will have to convert your generators to async functions with the new middleware signature:
+
+```js
+app.use(async ctx => {
+  const user = await Users.getById(this.session.user_id)
+  ctx.body = { message: 'some message' }
+})
+```
+
+Upgrading your middleware may require some work. One migration path is to update them one-by-one.
+
+1. Wrap all your current middleware in koa-convert
+2. Test
+3. npm outdated to see which koa middleware is outdated
+4. Update one outdated middleware, remove using koa-convert
+5. Test
+6. Repeat steps 3-5 until you're done
+
+
+## Updating Your Code
+
+You should start refactoring your code now to ease migrating to Koa v2:
+
+- Return promises everywhere!
+- Do not use `yield*`
+- Do not use `yield {}` or `yield []`.
+  - Convert `yield []` into `yield Promise.all([])`
+  - Convert `yield {}` into `yield Bluebird.props({})`
+
+You could also refactor your logic outside of Koa middleware functions. Create functions like 
+`function* someLogic(ctx) {}` and call it in your middleware as 
+`const result = yield someLogic(this)`.
+Not using `this` will help migrations to the new middleware signature, which does not use `this`.
+
+## Dependency Changes
+
+- [co](https://github.com/tj/co) is no longer bundled with Koa.  Require or import it directly.
+- [composition](https://github.com/thenables/composition) is no longer used and deprecated
+
+## ENV specific logging behavior removed
+
+An explicit check for the `test` environment was removed from error handling. 
+
+## V1 Support
+
+The v1.x branch is still supported and may also receive feature updates.  Except for this migration
+guide, Documentation will target the latest version.
+
+## Help Out
+
+If you encounter migration related issues not covered by this migration guide, please consider 
+submitting a documentation pull request.
diff --git a/lib/application.js b/lib/application.js
index ec30cdc2b..4c4dab414 100644
--- a/lib/application.js
+++ b/lib/application.js
@@ -107,8 +107,7 @@ module.exports = class Application extends Emitter {
     if (isGeneratorFunction(fn)) {
       deprecate('Support for generators will be removed in v3. ' +
                 'See the documentation for examples of how to convert old middleware ' +
-                'https://github.com/koajs/koa/blob/master/Readme.md' +
-                '#old-signature-middleware-v1x---deprecated');
+                'https://github.com/koajs/koa/blob/master/docs/migration.md');
       fn = convert(fn);
     }
     debug('use %s', fn._name || fn.name || '-');