diff --git a/docs/README.md b/docs/README.md
index 9f350f49..e5652ecb 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -22,4 +22,4 @@ The corresponding REST APIs can be accessed at:
 >
 > [`https://api.boltz.exchange/version`](https://api.boltz.exchange/version)
 
-In the following sections we'll walk through existing swap types & states, describe the REST API, how to handle refunds and more.
+In the following sections we'll describe the REST API, walk through swap types & states, how to craft transactions, handle refunds and more.
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
index 1e9b22b2..dfaae4aa 100644
--- a/docs/SUMMARY.md
+++ b/docs/SUMMARY.md
@@ -1,8 +1,8 @@
 # Table of contents
 
 * [👋 Introduction](README.md)
-* [🔁 Swap Types & States](lifecycle.md)
 * [🤖 REST API](api.md)
+* [🔁 Swap Types & States](lifecycle.md)
 * [🧾 Claiming Swaps & Refunds](claiming-swaps.md)
 * [⏩ 0-conf](0-conf.md)
 * [✨ Channel Creation](channel-creation.md)
diff --git a/docs/api.md b/docs/api.md
index ec7f015e..c5ea12b1 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -998,7 +998,7 @@ Response:
 
 There is one special case: when trying to broadcast a refund transaction for a swap that has not timed out yet, the backend will return some additional information in addition to the `error` in the `JSON` encoded response:
 
-* `error`: The reason why broadcasting failed. In this special case always: `non-mandatory-script-verify-flag (Locktime requirement not satisfied) (code 64)`
+* `error`: The reason why broadcasting failed. In this special case always: `non-mandatory-script-verify-flag (Locktime requirement not satisfied) (code 64)`.
 * `timeoutEta`: UNIX timestamp at which the HTLC is expected to time out.
 * `timeoutBlockHeight`: Block height at which the HTLC in the lockup transaction will time out.
 
@@ -1118,8 +1118,8 @@ Status Codes:
 Response object:
 
 * `nodes`:  `JSON` with the symbol of the chain on which the Lightning node is running as key and the following objects:
-  * `nodeKey`: public key of the lightning node
-  * `uris`: array of the URIs on which the lightning node is reachable
+  * `nodeKey`: Public key of the Lightning node.
+  * `uris`: Array of the URIs on which the Lightning node is reachable.
 
 **Examples:**
 
diff --git a/docs/claiming-swaps.md b/docs/claiming-swaps.md
index 45567477..e7b15513 100644
--- a/docs/claiming-swaps.md
+++ b/docs/claiming-swaps.md
@@ -1,15 +1,14 @@
 ---
 description: >-
-  This document describes how Boltz API clients craft claim transactions for
-  Reverse Submarine Swaps and refund transactions for failed Normal Submarine
-  Swaps.
+  This document describes how Boltz API clients craft claim and refund
+  transactions and emergency procedures for rescuing funds of failed swaps.
 ---
 
 # 🧾 Claiming Swaps & Refunds
 
 ## Basics
 
-lil intro
+Boltz API clients need to craft claim transactions for e.g. Reverse Submarine Swaps to claim the and refund transactions for failed Normal Submarine Swaps.
 
 ### UTXO Chains