diff --git a/docs/_advanced/ja_error_handling.md b/docs/_advanced/ja_error_handling.md
index c602e0912..8c05a5548 100644
--- a/docs/_advanced/ja_error_handling.md
+++ b/docs/_advanced/ja_error_handling.md
@@ -6,9 +6,9 @@ order: 1
---
-リスナーの中でエラーが発生した場合は、リスナー内で直接ハンドリングすることが望ましいでしょう。しかし、リスナーがすでに return した後でエラーが発生する場合もあります。 (`say()` または `respond()` を呼び出した場合や、必要なときに `ack()` を呼び出さなかった場合など)。このようなエラーはデフォルトではコンソールにログ出力されます。ユーザー自身がこうしたエラーを処理するには、`error(fn)` メソッドを使用してグローバルエラーハンドラーをアプリにアタッチします。
+*注: Bolt 2.x からエラーハンドリングが改善されました!詳細は [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。*
-エラーをよりスマートに管理するには、`client` キーの配下で (`say()` や `respond()` の代わりに) アプリにアタッチされている [`chat.postMessage`](https://api.slack.com/methods/chat.postMessage) メソッドを使用することをお勧めします。これにより `Promise` が返されるため、そこでエラーをキャッチして処理することができます。
+リスナーでエラーが発生した場合は `try`/`catch` を使って直接ハンドリングすることをおすすめします。しかし、それでもなおすり抜けてしまうエラーのパターンもあるでしょう。デフォルトでは、このようなエラーはコンソールにログ出力されます。ご自身でこれらをハンドリングするには、`error(fn)` メソッドによって、グローバルエラーハンドラーを定義してください。
```javascript
diff --git a/docs/_advanced/ja_middleware_global.md b/docs/_advanced/ja_middleware_global.md
index 7210c7d61..7dc595f44 100644
--- a/docs/_advanced/ja_middleware_global.md
+++ b/docs/_advanced/ja_middleware_global.md
@@ -11,6 +11,8 @@ order: 4
グローバルミドルウェアとリスナーミドルウェアは、いずれも、`await next()` を呼び出して実行チェーンの制御を次のミドルウェアに渡すか、`throw` を呼び出して以前に実行したミドルウェアチェーンにエラーを渡す必要があります。
たとえば、アプリが、対応する内部認証サービス (SSO プロバイダ、LDAP など) で識別されたユーザーにのみ応答する必要があるとします。この場合、グローバルミドルウェアを使用して認証サービス内のユーザーレコードを検索し、ユーザーが見つからない場合はエラーとなるように定義するのがよいでしょう。
+
+*注: Bolt 2.x からグローバルミドルウェアが `async` 関数をサポートしました!詳細は [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。*
```javascript
diff --git a/docs/_advanced/ja_middleware_listener.md b/docs/_advanced/ja_middleware_listener.md
index 5d902927c..19cd13f2c 100644
--- a/docs/_advanced/ja_middleware_listener.md
+++ b/docs/_advanced/ja_middleware_listener.md
@@ -13,6 +13,8 @@ order: 5
ただしもちろん、よりカスタマイズされた機能を追加するために、独自のミドルウェアを作成することもできます。独自のミドルウェアを記述する際には、関数で `await next()` を呼び出して制御を次のミドルウェアに渡すか、`throw` を呼び出して以前に実行されたミドルウェアチェーンにエラーを渡す必要があります。
たとえば、リスナーが人間からのメッセージのみを扱うのであれば、ボットメッセージを除外するリスナーミドルウェアを作成できます。
+
+*注: Bolt 2.x からミドルウェアが `async` 関数をサポートしました!詳細は [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。*
```javascript
diff --git a/docs/_basic/ja_listening_actions.md b/docs/_basic/ja_listening_actions.md
index 796c7455a..44de67bd1 100644
--- a/docs/_basic/ja_listening_actions.md
+++ b/docs/_basic/ja_listening_actions.md
@@ -12,6 +12,7 @@ order: 5
すべての `action()` の例で `ack()` が使用されていることに注目してください。Slack からイベントを受信したことを確認するために、アクションリスナー内で `ack()` 関数を呼び出す必要があります。これについては、「[イベントの確認](#acknowledge)」 セクションで説明しています。
+*注: Bolt 2.x からメッセージショートカット(以前はメッセージアクションと呼ばれていました)は `action()` ではなく `shortcut()` メソッドを使用するようになりました。詳細は [2.x マイグレーションガイド](https://slack.dev/bolt/ja-jp/tutorial/migration-v2)を参照してください。*
```javascript
diff --git a/docs/_tutorials/ja_hubot_migration.md b/docs/_tutorials/ja_hubot_migration.md
index b6b5c61e9..0a5da6667 100644
--- a/docs/_tutorials/ja_hubot_migration.md
+++ b/docs/_tutorials/ja_hubot_migration.md
@@ -1,6 +1,6 @@
---
title: Hubot のアプリを Bolt に移行する方法
-order: 1
+order: 2
slug: hubot-migration
lang: ja-jp
layout: tutorial
diff --git a/docs/_tutorials/ja_migration_v2.md b/docs/_tutorials/ja_migration_v2.md
new file mode 100644
index 000000000..5fca4dd56
--- /dev/null
+++ b/docs/_tutorials/ja_migration_v2.md
@@ -0,0 +1,120 @@
+---
+title: 2.x マイグレーションガイド
+order: 1
+slug: migration-v2
+lang: ja-jp
+layout: tutorial
+permalink: /ja-jp/tutorial/migration-v2
+---
+# 2.x マイグレーションガイド
+
+
+このガイドは Bolt 1.x を利用しているアプリを 2.x にアップグレードするための手順について説明します。
+
+
+---
+
+## リスナー関数を `async` 関数に変更
+
+Bolt アプリ内のリスナー関数は、全て `async` 関数に変更する必要があります。そして、そのリスナー関数内の `say()`、`respond()`、`ack()` メソッドの呼び出しも全て `await` を呼び出しの前につける必要があります。
+
+これまで:
+
+```javascript
+app.action('some-action-id', ({action, ack, say}) => {
+ ack();
+ say('hello world');
+})
+```
+
+これから:
+
+```javascript
+app.action('some-action-id', async ({action, ack, say}) => {
+ await ack();
+ await say('hello world');
+})
+```
+
+
+## エラーハンドリング
+
+Bolt for JavaScript 2.x では、より多くのユースケースで、必要に応じてエラーをキャッチし、グローバルエラーハンドラーにそれを送るかを制御できるよう改善されました。これまでと同様、グローバルエラーハンドラーに全て任せるよりは、可能な限り、リスナー関数の内部でエラーに対処することをおすすめします。
+
+### リスナー関数内で `try`/`catch` 節を用いたエラーハンドリング
+
+```javascript
+app.action('some-action-id', async ({action, ack, say, logger}) => {
+ try {
+ await ack();
+ await say('hello world');
+ } catch (error) {
+ // ここでエラーに対処
+ logger.error(error);
+ }
+})
+```
+
+### グローバルエラーハンドラーによるエラーハンドリング
+
+```javascript
+app.error((error) => {
+ // エラーの詳細をチェックして、メッセージ送信のリトライやアプリの停止などの対処を行う
+ console.error(error);
+});
+```
+
+その他のエラーに関する変更:
+
+- リスナー関数が `ack()` メソッドを 3 秒間のうちに呼び出さなかった場合、これまでのように例外を投げるのではなくログを出力するようになりました
+- もしミドルウェア実行中に複数のエラーが発生した場合、Bolt for JavaScript は `slack_bolt_multiple_listener_error` という `code` と全てのエラーで構成される配列を含む `original` というパラメーターをラップしたエラーを返します
+
+## メッセージショートカット
+
+[メッセージショートカット](https://api.slack.com/interactivity/shortcuts/using#message_shortcuts) (以前はメッセージアクションと呼ばれていました)は、これまで `action()` メソッドでハンドリングしていましたが `shortcut()` メソッドを使うようになりました。
+
+これまで:
+
+```javascript
+app.action('message-action-callback', ({action, ack, context}) => {
+ ack();
+ // ここで処理を行う
+})
+```
+
+これから:
+
+```javascript
+app.shortcut('message-action-callback', async ({shortcut, ack, context}) => {
+ await ack();
+ // Do stuff
+})
+```
+
+## ミドルウェアに関する変更
+
+もしカスタムのミドルウェアを書いている場合は、その関数を `async` に変更し、さらに `next()` の呼び出しを `await next()` に変更してください。もし後続の処理がある場合は、関数右を `next()` に渡す代わりに、その後続の処理を `await next()` の後に実行してください。
+
+これまで:
+
+```javascript
+function noBotMessages({message, next }) {
+ function doAfter() {
+ // 後続の処理をここでやる
+ }
+if (!message.subtype || message.subtype !== 'bot_message') {
+ next(doAfter);
+ }
+}
+```
+
+これから:
+
+```javascript
+async function noBotMessages({message, next }) {
+ if (!message.subtype || message.subtype !== 'bot_message') {
+ await next();
+ // 後続の処理をここでやる
+ }
+}
+```
\ No newline at end of file