doc/reference: reorder pages and update the landing page

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
 ```
 

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>
 ```
 

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>
 ```

doc/restapi_landing.md

@@ -8,11 +8,11 @@ relatedlinks: '[Directly interacting with the LXD 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