From de3c4aa64494850bdd24306cdfcd81259e14246a Mon Sep 17 00:00:00 2001
From: Ruth Fuchss <ruth.fuchss@canonical.com>
Date: Tue, 19 Mar 2024 17:42:56 +0100
Subject: [PATCH] doc/reference: reorder pages and update the landing page

Signed-off-by: Ruth Fuchss <ruth.fuchss@canonical.com>
---
 doc/explanation/instance_config.md |  6 +--
 doc/internals.md                   |  4 +-
 doc/reference/index.md             | 86 ++++++++++++++++++++++++++----
 doc/restapi_landing.md             |  6 +--
 4 files changed, 84 insertions(+), 18 deletions(-)

diff --git a/doc/explanation/instance_config.md b/doc/explanation/instance_config.md
index 4e61ed29720f..7a5363a900b3 100644
--- a/doc/explanation/instance_config.md
+++ b/doc/explanation/instance_config.md
@@ -34,12 +34,12 @@ Instance devices
   See {ref}`devices` for a reference of available devices and the corresponding instance device options, and {ref}`instances-configure-devices` for instructions on how to add and configure instance devices.
 
 ```{toctree}
-:maxdepth: 1
+:maxdepth: 2
 :hidden:
 
-../reference/devices.md
-../reference/instance_options.md
 ../reference/instance_properties.md
+../reference/instance_options.md
+../reference/devices.md
 ../reference/instance_units.md
 ```
 
diff --git a/doc/internals.md b/doc/internals.md
index 9f60cf81cd5d..4b3d260a83c6 100644
--- a/doc/internals.md
+++ b/doc/internals.md
@@ -3,10 +3,10 @@
 ```{filtered-toctree}
 :titlesonly:
 
-:diataxis:/daemon-behavior
 :diataxis:/environment
-:diataxis:/syscall-interception
 :diataxis:/reference/uefi_variables
+:diataxis:/daemon-behavior
+:diataxis:/syscall-interception
 :diataxis:User namespace setup </userns-idmap>
 ```
 
diff --git a/doc/reference/index.md b/doc/reference/index.md
index d1d94c53ec11..2b7b9175339c 100644
--- a/doc/reference/index.md
+++ b/doc/reference/index.md
@@ -3,26 +3,92 @@
 
 The reference material in this section provides technical descriptions of LXD.
 
+## General information
+
+Before you start using LXD, you should check the system requirements.
+You should also be aware of the supported architectures, the available image servers, the format for images, and the environment used for containers.
+
 ```{toctree}
 :titlesonly:
 :maxdepth: 2
 
+/requirements
 /architectures
-/reference/cluster_member_config
-Configuration option index </config-options>
-Container environment </container-environment>
+/reference/remote_image_servers
 /reference/image_format
+Container environment </container-environment>
+```
+
+## Configuration options
+
+LXD is highly configurable.
+Check the available configuration options for the LXD server and the different entities used in LXD.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+:includehidden:
+
+Configuration option index </config-options>
+/server
 /explanation/instance_config
-/internals
-/reference/manpages
+/reference/projects
+/reference/storage_drivers
 /reference/networks
+Cluster configuration </reference/cluster_member_config>
+```
+
+## Production setup
+
+Once you are ready for production, make sure your LXD server is configured to support the required load.
+You should also regularly {ref}`monitor the server metrics <metrics>`.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
 Production server settings </reference/server_settings>
-/reference/projects
 /reference/provided_metrics
-/reference/remote_image_servers
-/requirements
+```
+
+## REST API
+
+All communication between LXD and its clients happens using a RESTful API over HTTP.
+Check the list of API extensions to see if a feature is available in your version of the API.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
 /restapi_landing
-/server
-/reference/storage_drivers
+```
+
+## Man pages
+
+`lxc` is the command line client for LXD.
+Its usage is documented in the help pages for the `lxc` commands and subcommands.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+/reference/manpages
+```
+
+## Implementation details
+
+You don't need to be aware of the internal implementation details to use LXD.
+However, advanced users might be interested in knowing what happens internally.
+
+```{toctree}
+:titlesonly:
+:maxdepth: 2
+
+/internals
+```
+
+```{toctree}
+:hidden:
+
 Project repository <https://github.com/canonical/lxd>
 ```
diff --git a/doc/restapi_landing.md b/doc/restapi_landing.md
index 52529fdf241f..dbd2803fe6a9 100644
--- a/doc/restapi_landing.md
+++ b/doc/restapi_landing.md
@@ -8,11 +8,11 @@ relatedlinks: '[Directly&#32;interacting&#32;with&#32;the&#32;LXD&#32;API](https
 ```{toctree}
 :maxdepth: 1
 
-Events API documentation <events>
-Instance API <dev-lxd>
 Main API documentation <rest-api>
-Main API extensions <api-extensions>
 api
+Main API extensions <api-extensions>
+Events API documentation <events>
+Instance API <dev-lxd>
 ```
 
 ## Related topics