From 7b6e5071518c726b9e9371bbfc8bb9beb81f50b9 Mon Sep 17 00:00:00 2001
From: Robert Helgesson <robert@rycee.net>
Date: Sun, 26 Feb 2023 15:54:37 +0100
Subject: [PATCH] docs: slight improvement of Flake documentation

---
 docs/installation.adoc |  7 +++++++
 docs/nix-flakes.adoc   | 25 +++++++++++++++++++++++--
 2 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/docs/installation.adoc b/docs/installation.adoc
index afdbe35e..b06ab243 100644
--- a/docs/installation.adoc
+++ b/docs/installation.adoc
@@ -2,6 +2,7 @@
 == Installing Home Manager
 
 :nix-darwin: https://github.com/LnL7/nix-darwin/
+:nixos-wiki-flakes: https://nixos.wiki/wiki/Flakes
 
 Home Manager can be used in three primary ways:
 
@@ -22,6 +23,12 @@ This allows the user profiles to be built together with the system
 when running `darwin-rebuild`. See <<sec-install-nix-darwin-module>>
 for a description of this setup.
 
+[NOTE]
+In this chapter we describe how to install Home Manager in the
+standard way using channels. If you prefer to use
+{nixos-wiki-flakes}[Nix Flakes] then please see the instructions in
+<<ch-nix-flakes>>.
+
 [[sec-install-standalone]]
 === Standalone installation
 
diff --git a/docs/nix-flakes.adoc b/docs/nix-flakes.adoc
index 2e00c9e6..98e66bb2 100644
--- a/docs/nix-flakes.adoc
+++ b/docs/nix-flakes.adoc
@@ -3,8 +3,29 @@
 
 :nixos-wiki-flakes: https://nixos.wiki/wiki/Flakes
 
-Home Manager includes a `flake.nix` file for compatibility with {nixos-wiki-flakes}[Nix Flakes].
-The support is still experimental and may change in backwards incompatible ways.
+Home Manager is compatible with {nixos-wiki-flakes}[Nix Flakes]. But
+please be aware that the support it is still experimental and may
+change in backwards incompatible ways.
+
+Just like in the standard installation you can use the Home Manager
+flake in three ways:
+
+1. Using the standalone `home-manager` tool. For platforms other than
+NixOS and Darwin, this is the only available choice. It is also
+recommended for people on NixOS or Darwin that want to manage their
+home directory independently of the system as a whole. See
+<<sec-flakes-standalone>> for instructions on how to perform this
+installation.
+
+2. As a module within a NixOS system configuration. This allows the
+user profiles to be built together with the system when running
+`nixos-rebuild`. See <<sec-flakes-nixos-module>> for a description of
+this setup.
+
+3. As a module within a {nix-darwin}[nix-darwin] system configuration.
+This allows the user profiles to be built together with the system
+when running `darwin-rebuild`. See <<sec-flakes-nix-darwin-module>>
+for a description of this setup.
 
 [[sec-flakes-prerequisites]]
 === Prerequisites