diff --git a/doc/manual/src/command-ref/files/channels.md b/doc/manual/src/command-ref/files/channels.md
index 7b1f27128..55a25e8de 100644
--- a/doc/manual/src/command-ref/files/channels.md
+++ b/doc/manual/src/command-ref/files/channels.md
@@ -1,26 +1,41 @@
 ## Channels
 
-A directory containing symlinks to Nix channels, managed by [`nix-channel`]:
+Channels are a mechanism for obtaining Nix expressions over the web.
+
+The moving parts of channels are:
+- The official channels listed at <https://nixos.org/channels>
+- The user-specific list of [subscribed channels](#subscribed-channels)
+- The [downloaded channel contents](#channel-contents)
+- The [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path)
+
+> **Note**
+>
+> The state of a subscribed channel is external to the Nix expressions relying on it.
+> This may limit reproducibility.
+>
+> Dependencies on other Nix expressions can be declared explicitly with:
+> - [`fetchurl`](@docroot@/language/builtins.md#builtins-fetchurl), [`fetchTarball`](@docroot@/language/builtins.md#builtins-fetchTarball), or [`fetchGit`](@docroot@/language/builtins.md#builtins-fetchGit) in Nix expressions
+> - the [`-I` option](@docroot@/command-ref/opt-common.md#opt-I) in command line invocations for explicitly modifying the value of [lookup paths](@docroot@/language/constructs/lookup-path.md)
+
+## Subscribed channels
+
+The list of subscribed channels is stored in a file:
+
+- `~/.nix-channels`
+- `$XDG_STATE_HOME/nix/channels` if [`use-xdg-base-directories`](@docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories) is set to `true`
+
+Each line maps a channel name to a URL in the following format:
+
+```
+<url> <name>
+```
+
+## Channels contents
+
+The [`nix-channel`](@docroot@/command-ref/nix-channel.md) command uses a [profile](@docroot@/command-ref/files/profiles.md) to keep track of channels:
 
 - `$XDG_STATE_HOME/nix/profiles/channels` for regular users
 - `$NIX_STATE_DIR/profiles/per-user/root/channels` for `root`
 
-[`nix-channel`] uses a [profile](@docroot@/command-ref/files/profiles.md) to store channels.
-This profile contains symlinks to the contents of those channels.
-
-## Subscribed channels
-
-The list of subscribed channels is stored in
-
-- `~/.nix-channels`
-- `$XDG_STATE_HOME/nix/channels` if [`use-xdg-base-directories`] is set to `true`
-
-in the following format:
-
-```
-<url> <name>
-...
-```
-
-[`nix-channel`]: @docroot@/command-ref/nix-channel.md
-[`use-xdg-base-directories`]: @docroot@/command-ref/conf-file.md#conf-use-xdg-base-directories
+Each generation of that profile is a directory with symlinks to channel contents.
+Each entry in this directory corresponds to the name of a [subscribed channel](#subscribed-channels) at that time.
diff --git a/doc/manual/src/command-ref/nix-channel.md b/doc/manual/src/command-ref/nix-channel.md
index 8b58392b7..2a6681c0c 100644
--- a/doc/manual/src/command-ref/nix-channel.md
+++ b/doc/manual/src/command-ref/nix-channel.md
@@ -1,6 +1,6 @@
 # Name
 
-`nix-channel` - manage Nix channels
+`nix-channel` - manage [channels](#channels)
 
 # Synopsis
 
@@ -8,24 +8,12 @@
 
 # Description
 
-Channels are a mechanism for referencing remote Nix expressions and conveniently retrieving their latest version.
+This command allows
+- Managing a list of [subscribed channels](#subscribed-channels)
+- Retrieval of the [contents](#channel-contents) of subscribed channels
+- Restoring the contents of channels to previously retrieved versions
 
-The moving parts of channels are:
-- The official channels listed at <https://nixos.org/channels>
-- The user-specific list of [subscribed channels](#subscribed-channels)
-- The [downloaded channel contents](#channels)
-- The [Nix expression search path](@docroot@/command-ref/conf-file.md#conf-nix-path), set with the [`-I` option](#opt-i) or the [`NIX_PATH` environment variable](#env-NIX_PATH)
-
-> **Note**
->
-> The state of a subscribed channel is external to the Nix expressions relying on it.
-> This may limit reproducibility.
->
-> Dependencies on other Nix expressions can be declared explicitly with:
-> - [`fetchurl`](@docroot@/language/builtins.md#builtins-fetchurl), [`fetchTarball`](@docroot@/language/builtins.md#builtins-fetchTarball), or [`fetchGit`](@docroot@/language/builtins.md#builtins-fetchGit) in Nix expressions
-> - the [`-I` option](@docroot@/command-ref/opt-common.md#opt-I) in command line invocations
-
-This command has the following operations:
+It has the following operations:
 
 - `--add` *url* \[*name*\]