diff --git a/src/dispatching/repls.rs b/src/dispatching/repls.rs
index 0d41d7ba..18fac935 100644
--- a/src/dispatching/repls.rs
+++ b/src/dispatching/repls.rs
@@ -1,9 +1,9 @@
 //! [REPL]s for dispatching updates.
 //!
-//! This module provides functions for easy update handling, that accept a
+//! This module provides utilities for easy update handling. They accept a
 //! single "handler" function that processes all updates of a certain kind. Note
-//! that REPLs are meant to be used as a prototyping tool and lack configuration
-//! and some advanced features.
+//! that REPLs are meant to be used for simple scenarios, such as prototyping,
+//! inasmuch they lack configuration and some advanced features.
 //!
 //! [REPL]: https://en.wikipedia.org/wiki/Read-eval-print_loop
 
diff --git a/src/dispatching/repls/commands_repl.rs b/src/dispatching/repls/commands_repl.rs
index f3c25cfe..b988d06b 100644
--- a/src/dispatching/repls/commands_repl.rs
+++ b/src/dispatching/repls/commands_repl.rs
@@ -22,19 +22,17 @@ use teloxide_core::requests::Requester;
 /// Don't be scared by many trait bounds in the signature, in essence they
 /// require:
 ///
-/// 1. `bot` is a bot, client for the Telegram bot API
-///    - in teloxide this is represented via a [`Requester`] trait
-/// 2. `handler` is an async function that returns `Result<(), E>`
-///    - Such that `E` can be printed with [`Debug`] formatting
-///    - And all arguments can be extracted from [`DependencyMap`]
-///       - Which is the same, as all arguments implementing `Send + Sync +
-///         'static`
-/// 3. `cmd` is a type of the command that will be parsed,
-///    - The command type must implement [`BotCommands`] trait
-///    - It can be acquired by writing `TheCommandType::ty()`
+/// 1. `bot` is a bot, client for the Telegram bot API. It is represented via
+///    the [`Requester`] trait.
+/// 2. `handler` is an `async` function that takes arguments from
+///    [`DependencyMap`] (see below) and returns [`ResponseResult`].
+/// 3. `cmd` is a type hint for your command enumeration
+///    `MyCommand`: just write `MyCommand::ty()`. Note that `MyCommand` must
+///    implement the [`BotCommands`] trait, typically via
+///   `#[derive(BotCommands)]`.
 ///
-/// All other requirements are about thread safety and data validity and can be
-/// ignored for most of the time.
+/// All the other requirements are about thread safety and data validity and can
+/// be ignored for most of the time.
 ///
 /// ## Handler arguments
 ///
@@ -85,20 +83,18 @@ where
 /// Don't be scared by many trait bounds in the signature, in essence they
 /// require:
 ///
-/// 1. `bot` is a bot, client for the Telegram bot API
-///    - in teloxide this is represented via a [`Requester`] trait
-/// 2. `handler` is an async function that returns `Result<(), E>`
-///    - Such that `E` can be printed with [`Debug`] formatting
-///    - And all arguments can be extracted from [`DependencyMap`]
-///       - Which is the same, as all arguments implementing `Send + Sync +
-///         'static`
-/// 3. `listener` is an [`UpdateListener`]
-/// 4. `cmd` is a type of the command that will be parsed,
-///    - The command type must implement [`BotCommands`] trait
-///    - It can be acquired by writing `TheCommandType::ty()`
+/// 1. `bot` is a bot, client for the Telegram bot API. It is represented via
+///    the [`Requester`] trait.
+/// 2. `handler` is an `async` function that takes arguments from
+///    [`DependencyMap`] (see below) and returns [`ResponseResult`].
+/// 3. `listener` is something that takes updates from a Telegram server and
+///    implements [`UpdateListener`].
+/// 4. `cmd` is a type hint for your command enumeration `MyCommand`: just
+///    write `MyCommand::ty()`. Note that `MyCommand` must implement the
+///   [`BotCommands`] trait, typically via `#[derive(BotCommands)]`.
 ///
-/// All other requirements are about thread safety and data validity and can be
-/// ignored for most of the time.
+/// All the other requirements are about thread safety and data validity and can
+/// be ignored for most of the time.
 ///
 /// ## Handler arguments
 ///
diff --git a/src/dispatching/repls/repl.rs b/src/dispatching/repls/repl.rs
index 3a63d440..8edf5828 100644
--- a/src/dispatching/repls/repl.rs
+++ b/src/dispatching/repls/repl.rs
@@ -19,13 +19,10 @@ use teloxide_core::requests::Requester;
 /// Don't be scared by many trait bounds in the signature, in essence they
 /// require:
 ///
-/// 1. `bot` is a bot, client for the Telegram bot API
-///    - in teloxide this is represented via a [`Requester`] trait
-/// 2. `handler` is an async function that returns `Result<(), E>`
-///    - Such that `E` can be printed with [`Debug`] formatting
-///    - And all arguments can be extracted from [`DependencyMap`]
-///       - Which is the same, as all arguments implementing `Send + Sync +
-///         'static`
+/// 1. `bot` is a bot, client for the Telegram bot API. It is represented via
+///    the [`Requester`] trait.
+/// 2. `handler` is an `async` function that takes arguments from
+///    [`DependencyMap`] (see below) and returns [`ResponseResult`].
 ///
 /// ## Handler arguments
 ///
@@ -68,14 +65,12 @@ where
 /// Don't be scared by many trait bounds in the signature, in essence they
 /// require:
 ///
-/// 1. `bot` is a bot, client for the Telegram bot API
-///    - in teloxide this is represented via a [`Requester`] trait
-/// 2. `handler` is an async function that returns `Result<(), E>`
-///    - Such that `E` can be printed with [`Debug`] formatting
-///    - And all arguments can be extracted from [`DependencyMap`]
-///       - Which is the same, as all arguments implementing `Send + Sync +
-///         'static`
-/// 3. `listener` is an [`UpdateListener`]
+/// 1. `bot` is a bot, client for the Telegram bot API. It is represented via
+///    the [`Requester`] trait.
+/// 2. `handler` is an `async` function that takes arguments from
+///    [`DependencyMap`] (see below) and returns [`ResponseResult`].
+/// 3. `listener` is something that takes updates from a Telegram server and
+///    implements [`UpdateListener`].
 ///
 /// ## Handler arguments
 ///
diff --git a/src/dispatching/repls/stopping.md b/src/dispatching/repls/stopping.md
index 63c65e28..b5733e84 100644
--- a/src/dispatching/repls/stopping.md
+++ b/src/dispatching/repls/stopping.md
@@ -1,4 +1,4 @@
-To stop repl, simply press `Ctrl`+`C` in the terminal where you run the program.
-Note that gracefully stopping can take some time (we plan to improve this, see [#711]).
+To stop a REPL, simply press `Ctrl`+`C` in the terminal where you run the program.
+Note that graceful shutdown may take some time (we plan to improve this, see [#711]).
 
 [#711]: https://github.com/teloxide/teloxide/issues/711