doc: add an operations&maintenance section and move some pages there

16 files changed, 38 insertions, 19 deletions

diff --git a/doc/book/build/_index.md b/doc/book/build/_index.md
index 9bb17086..021045aa 100644
--- a/doc/book/build/_index.md
+++ b/doc/book/build/_index.md
@@ -1,6 +1,6 @@
 +++
 title = "Build your own app"
-weight = 4
+weight = 40
 sort_by = "weight"
 template = "documentation.html"
 +++
diff --git a/doc/book/connect/_index.md b/doc/book/connect/_index.md
index 93a2b87e..7d8e686c 100644
--- a/doc/book/connect/_index.md
+++ b/doc/book/connect/_index.md
@@ -1,6 +1,6 @@
 +++
 title = "Existing integrations"
-weight = 3
+weight = 30
 sort_by = "weight"
 template = "documentation.html"
 +++
diff --git a/doc/book/cookbook/_index.md b/doc/book/cookbook/_index.md
index 07bf6ebf..ff90ad52 100644
--- a/doc/book/cookbook/_index.md
+++ b/doc/book/cookbook/_index.md
@@ -1,7 +1,7 @@
 +++
 title="Cookbook"
 template = "documentation.html"
-weight = 2
+weight = 20
 sort_by = "weight"
 +++
 
@@ -37,7 +37,3 @@ This chapter could also be referred as "Tutorials" or "Best practices".
 - **[Monitoring Garage](@/documentation/cookbook/monitoring.md)** This page
   explains the Prometheus metrics available for monitoring the Garage
   cluster/nodes.
-
-- **[Recovering from failures](@/documentation/cookbook/recovering.md):** Garage's first selling point is resilience
-  to hardware failures. This section explains how to recover from such a failure in the
-  best possible way.
diff --git a/doc/book/cookbook/real-world.md b/doc/book/cookbook/real-world.md
index 0b9e016c..7061069f 100644
--- a/doc/book/cookbook/real-world.md
+++ b/doc/book/cookbook/real-world.md
@@ -345,7 +345,7 @@ garage layout apply
 ```
 
 **WARNING:** if you want to use the layout modification commands in a script,
-make sure to read [this page](@/documentation/reference-manual/layout.md) first.
+make sure to read [this page](@/documentation/operations/layout.md) first.
 
 
 ## Using your Garage cluster
diff --git a/doc/book/design/_index.md b/doc/book/design/_index.md
index 50933139..5881ab8f 100644
--- a/doc/book/design/_index.md
+++ b/doc/book/design/_index.md
@@ -1,6 +1,6 @@
 +++
 title = "Design"
-weight = 6
+weight = 70
 sort_by = "weight"
 template = "documentation.html"
 +++
diff --git a/doc/book/design/internals.md b/doc/book/design/internals.md
index 777e017d..cefb7acc 100644
--- a/doc/book/design/internals.md
+++ b/doc/book/design/internals.md
@@ -61,7 +61,7 @@ Garage prioritizes which nodes to query according to a few criteria:
 
 
 For further reading on the cluster structure look at the [gateway](@/documentation/cookbook/gateways.md) 
-and [cluster layout management](@/documentation/reference-manual/layout.md) pages.
+and [cluster layout management](@/documentation/operations/layout.md) pages.
 
 ## Garbage collection
 
diff --git a/doc/book/development/_index.md b/doc/book/development/_index.md
index 8e730bf6..2b2af0cc 100644
--- a/doc/book/development/_index.md
+++ b/doc/book/development/_index.md
@@ -1,6 +1,6 @@
 +++
 title = "Development"
-weight = 7
+weight = 80
 sort_by = "weight"
 template = "documentation.html"
 +++
diff --git a/doc/book/operations/_index.md b/doc/book/operations/_index.md
new file mode 100644
index 00000000..16d0e9d5
--- /dev/null
+++ b/doc/book/operations/_index.md
@@ -0,0 +1,23 @@
++++
+title = "Operations & Maintenance"
+weight = 50
+sort_by = "weight"
+template = "documentation.html"
++++
+
+This section contains a number of important information on how to best operate a Garage cluster,
+to ensure integrity and availability of your data:
+
+- **[Upgrading Garage](@/documentation/operations/upgrading.md):** General instructions on how to
+  upgrade your cluster from one version to the next. Instructions specific for each version upgrade
+  can bef ound in the [working documents](@/documentation/working-documents/_index.md) section.
+
+- **[Layout management](@/documentation/operations/layout.md):** Best practices for using the `garage layout`
+  commands when adding or removing nodes from your cluster.
+
+- **[Durability and repairs](@/documentation/operations/durability-repairs.md):** How to check for small things
+  that might be going wrong, and how to recover from such failures.
+
+- **[Recovering from failures](@/documentation/operations/recovering.md):** Garage's first selling point is resilience
+  to hardware failures. This section explains how to recover from such a failure in the
+  best possible way.
diff --git a/doc/book/cookbook/durability-repairs.md b/doc/book/operations/durability-repairs.md
index 46eb25b8..b8992f85 100644
--- a/doc/book/cookbook/durability-repairs.md
+++ b/doc/book/operations/durability-repairs.md
@@ -1,6 +1,6 @@
 +++
 title = "Durability & Repairs"
-weight = 50
+weight = 30
 +++
 
 To ensure the best durability of your data and to fix any inconsistencies that may
diff --git a/doc/book/reference-manual/layout.md b/doc/book/operations/layout.md
index a7d6f51f..5e314246 100644
--- a/doc/book/reference-manual/layout.md
+++ b/doc/book/operations/layout.md
@@ -1,6 +1,6 @@
 +++
 title = "Cluster layout management"
-weight = 50
+weight = 20
 +++
 
 The cluster layout in Garage is a table that assigns to each node a role in
diff --git a/doc/book/cookbook/recovering.md b/doc/book/operations/recovering.md
index 1c6a6763..7a830788 100644
--- a/doc/book/cookbook/recovering.md
+++ b/doc/book/operations/recovering.md
@@ -1,6 +1,6 @@
 +++
 title = "Recovering from failures"
-weight = 60
+weight = 40
 +++
 
 Garage is meant to work on old, second-hand hardware.
diff --git a/doc/book/cookbook/upgrading.md b/doc/book/operations/upgrading.md
index 5a2850c0..e8919a19 100644
--- a/doc/book/cookbook/upgrading.md
+++ b/doc/book/operations/upgrading.md
@@ -1,6 +1,6 @@
 +++
 title = "Upgrading Garage"
-weight = 70
+weight = 10
 +++
 
 Garage is a stateful clustered application, where all nodes are communicating together and share data structures.
diff --git a/doc/book/quick-start/_index.md b/doc/book/quick-start/_index.md
index f01789a3..f556eaa3 100644
--- a/doc/book/quick-start/_index.md
+++ b/doc/book/quick-start/_index.md
@@ -1,6 +1,6 @@
 +++
 title = "Quick Start"
-weight = 0
+weight = 10
 sort_by = "weight"
 template = "documentation.html"
 +++
diff --git a/doc/book/reference-manual/_index.md b/doc/book/reference-manual/_index.md
index ab1de5e6..1f360e57 100644
--- a/doc/book/reference-manual/_index.md
+++ b/doc/book/reference-manual/_index.md
@@ -1,6 +1,6 @@
 +++
 title = "Reference Manual"
-weight = 5
+weight = 60
 sort_by = "weight"
 template = "documentation.html"
 +++
diff --git a/doc/book/reference-manual/features.md b/doc/book/reference-manual/features.md
index 550504ff..2f8e633a 100644
--- a/doc/book/reference-manual/features.md
+++ b/doc/book/reference-manual/features.md
@@ -35,7 +35,7 @@ This makes setting up and administering storage clusters, we hope, as easy as it
 
 A Garage cluster can very easily evolve over time, as storage nodes are added or removed.
 Garage will automatically rebalance data between nodes as needed to ensure the desired number of copies.
-Read about cluster layout management [here](@/documentation/reference-manual/layout.md).
+Read about cluster layout management [here](@/documentation/operations/layout.md).
 
 ### No RAFT slowing you down
 
diff --git a/doc/book/working-documents/_index.md b/doc/book/working-documents/_index.md
index 8fc170b7..fe79e65d 100644
--- a/doc/book/working-documents/_index.md
+++ b/doc/book/working-documents/_index.md
@@ -1,6 +1,6 @@
 +++
 title = "Working Documents"
-weight = 8
+weight = 90
 sort_by = "weight"
 template = "documentation.html"
 +++