diff --git a/substrate/frame/benchmarking/src/lib.rs b/substrate/frame/benchmarking/src/lib.rs
index 625da2a24bd0..6e21356e9d47 100644
--- a/substrate/frame/benchmarking/src/lib.rs
+++ b/substrate/frame/benchmarking/src/lib.rs
@@ -311,6 +311,83 @@ pub use v1::*;
 /// 	}
 /// }
 /// ```
+///
+/// ## Migrate from v1 to v2
+///
+/// To migrate your code from benchmarking v1 to benchmarking v2, you may follow these
+/// steps:
+/// 1. Change the import from `frame_benchmarking::v1::` to `frame_benchmarking::v2::*`, or
+///    `frame::benchmarking::prelude::*` under the umbrella crate;
+/// 2. Move the code inside the v1 `benchmarks! { ... }` block to the v2 benchmarks module `mod
+///    benchmarks { ... }` under the benchmarks macro (`#[benchmarks]` for a regular module, or
+///    `#[instance_benchmarks]` to set up the module in instance benchmarking mode);
+/// 3. Turn each v1 benchmark into a function inside the v2 benchmarks module with the same name,
+///    having either a blank return type or a return type compatible with `Result<(),
+///    BenchmarkError>`. For instance, `foo { ... }` can become `fn foo() -> Result<(),
+///    BenchmarkError>`. More in detail:
+///    1. Move all the v1 complexity parameters as [ParamRange](`v2::ParamRange`) arguments to the
+///       v2 function, and their setup code to the body of the function. For instance, `let y in 0
+///       .. 10 => setup(y)?;` from v1 will give a `y: Linear<0, 10>` argument to the corresponding
+///       function in v2, while `setup(y)?;` will be moved to the body of the function;
+///    2. Move all the v1 setup code to the body of the v2 function;
+///    3. Move the benchmarked code to the body of the v2 function under the appropriate macro
+///       attribute: `#[extrinsic_call]` for extrinsic pallet calls and `#[block]` for blocks of
+///       code;
+///    4. Move the v1 verify code block to the body of the v2 function, after the
+///       `#[extrinsic_call]` or `#[block]` attribute.
+///    5. If the function returns a `Result<(), BenchmarkError>`, end with `Ok(())`.
+///
+/// As for tests, the code is the same as v1 (see [Benchmark Tests](#benchmark-tests)).
+///
+/// As an example migration, the following v1 code
+///
+/// ```ignore
+/// #![cfg(feature = "runtime-benchmarks")]
+///
+/// use frame_benchmarking::v1::*;
+///
+/// benchmarks! {
+///
+///   // first dispatchable: this is a user dispatchable and operates on a `u8` vector of
+///   // size `l`
+///   foo {
+///     let caller = funded_account::<T>(b"caller", 0);
+///     let l in 1 .. 10_000 => initialize_l(l);
+///   }: {
+///     _(RuntimeOrigin::Signed(caller), vec![0u8; l])
+///   } verify {
+///     assert_last_event::<T>(Event::FooExecuted { result: Ok(()) }.into());
+///   }
+/// }
+/// ```
+///
+/// would become the following v2 code:
+///
+/// ```ignore
+/// #![cfg(feature = "runtime-benchmarks")]
+///
+/// use frame_benchmarking::v2::*;
+///
+/// #[benchmarks]
+/// mod benchmarks {
+///   use super::*;
+///
+///   // first dispatchable: foo; this is a user dispatchable and operates on a `u8` vector of
+///   // size `l`
+///   #[benchmark]
+///   fn foo(l: Linear<1 .. 10_000>) -> Result<(), BenchmarkError> {
+///     let caller = funded_account::<T>(b"caller", 0);
+///     initialize_l(l);
+///
+///     #[extrinsic_call]
+///     _(RuntimeOrigin::Signed(caller), vec![0u8; l]);
+///     
+///     // Everything onwards will be treated as test.
+///     assert_last_event::<T>(Event::FooExecuted { result: Ok(()) }.into());
+///     Ok(())
+///   }
+/// }
+/// ```
 pub mod v2 {
 	pub use super::*;
 	pub use frame_support_procedural::{