Make explanation section more consistent with how-tos (#229)

* Make explanation section more consistent with how-tos
* Fill empty descriptions
* Fix broken links

Author: s-makin

explanation/active-directory.rst

@@ -3,17 +3,33 @@
 Active Directory integration
 *****************************
 
-* :ref:`Choosing an integration method <choosing-an-integration-method>`
-* :ref:`Security identifiers (SIDs) <security-identifiers-sids>`
-* :ref:`Identity Mapping (idmap) backends <identity-mapping-idmap-backends>`
-* :ref:`The rid idmap backend <the-rid-idmap-backend>`
-* :ref:`The autorid idmap backend <the-autorid-idmap-backend>`
+If you have a Microsoft Active Directory domain set up, you can join your
+Ubuntu Server to it.
+
+Introduction
+============
+
+.. toctree::
+   :titlesonly:
+
+   intro-to/AD-integration
+
+Configuration
+=============
+
+This section will talk you through the options available and help you make the
+appropriate choices for your setup.
 
 .. toctree::
-    :hidden:
+   :titlesonly:
+
+   Choosing an integration method <active-directory/choosing-an-integration-method>
+   Security identifiers (SIDs) <active-directory/security-identifiers-sids>
+   Identity Mapping (idmap) backends <active-directory/identity-mapping-idmap-backends>
+   The rid idmap backend <active-directory/the-rid-idmap-backend>
+   The autorid idmap backend <active-directory/the-autorid-idmap-backend>
+
+See also
+========
 
-    Choosing an integration method <active-directory/choosing-an-integration-method>
-    Security identifiers (SIDs) <active-directory/security-identifiers-sids>
-    Identity Mapping (idmap) backends <active-directory/identity-mapping-idmap-backends>
-    The rid idmap backend <active-directory/the-rid-idmap-backend>
-    The autorid idmap backend <active-directory/the-autorid-idmap-backend>
+* How-to: :ref:`how-to-active-directory-integration`

explanation/cryptography.rst

@@ -3,16 +3,19 @@
 Cryptography
 *************
 
-* :ref:`OpenSSL <openssl>`
-* :ref:`GnuTLS <gnutls>`
-* :ref:`Network Security Services (NSS) <network-security-services-nss>`
-* :ref:`Java cryptography configuration <java-cryptography-configuration>`
-* :ref:`BIND 9 DNSSEC cryptography selection <bind-9-dnssec-cryptography-selection>`
-* :ref:`OpenSSH crypto configuration <openssh-crypto-configuration>`
-* :ref:`Troubleshooting TLS/SSL <troubleshooting-tls-ssl>`
+.. toctree::
+   :titlesonly:
+
+   intro-to/crypto-libraries
+
+Common crypto libraries
+=======================
+
+These pages discuss various popular cryptographic libraries that are commonly
+found in Ubuntu.
 
 .. toctree::
-    :hidden:
+   :titlesonly:
 
     OpenSSL <crypto/openssl>
     GnuTLS <crypto/gnutls>
@@ -21,3 +24,4 @@ Cryptography
     BIND 9 DNSSEC cryptography selection <crypto/bind-9-dnssec-cryptography-selection>
     OpenSSH crypto configuration <crypto/openssh-crypto-configuration>
     Troubleshooting TLS/SSL <crypto/troubleshooting-tls-ssl>
+

explanation/data-and-storage.rst

@@ -0,0 +1,47 @@
+.. _explanation-data-and-storage:
+
+Data and storage
+****************
+
+The following sections provide details on various topics related to storing,
+managing and accessing data.
+
+Data management
+===============
+
+OpenLDAP is a popular implementation of the Lightweight Directory Access
+Protocol (LDAP), used for managing hierarchical data.
+
+.. toctree::
+   :titlesonly:
+
+   intro-to/openldap
+
+Databases are also a common data management tool in any setup. 
+
+.. toctree::
+   :titlesonly:
+
+   intro-to/databases
+
+Storage and backups
+===================
+
+* Our :ref:`explanation-storage` section contains more detail about LVM and
+  iSCSI
+* Our :ref:`explanation-multipath` section explains the key concepts and common
+  configuration setups for Device Mapper Multipathing
+* :ref:`introduction-to-backups` discusses various backup strategies to protect
+  your data
+
+.. toctree::
+   :hidden:
+
+   storage
+   multipath
+   intro-to/backups
+
+See also
+========
+
+* How-to: :ref:`how-to-data-and-storage`

explanation/high-availability.rst

@@ -1,13 +1,32 @@
 .. _explanation-high-availability:
 
-High availability
+High Availability
 ******************
 
+High Availability is a way to ensure minimal downtime if and when system
+failures occur by using redundancy, failover and load balancing to keep
+services running.
+
+Introduction
+============
+
+* :ref:`Introduction to High Availability <introduction-to-high-availability>`
+
+Key concepts
+============
+
 * :ref:`Pacemaker resource agents <pacemaker-resource-agents>`
 * :ref:`Pacemaker fence agents <pacemaker-fence-agents>`
 
 .. toctree::
     :hidden:
 
+    Introduction to HA <intro-to/high-availability>
     Pacemaker resource agents <high-availability/pacemaker-resource-agents>
     Pacemaker fence agents <high-availability/pacemaker-fence-agents>
+
+See also
+========
+
+* How-to: :ref:`Set up a Distributed Replicated Block Device (DRBD) <install-drbd>`
+* Reference: :ref:`reference-high-availability`

explanation/index.rst

@@ -8,86 +8,126 @@ understanding of how Ubuntu Server works and how it can be used and configured.
 They enable you to expand your knowledge, making the operating system easier
 to use.
 
-Introduction to...
-==================
-
-.. include:: introduction-to.rst
-    :start-line: 4
-    :end-before: .. toctree::
+If you're not sure how or where to get started with a topic, each section has
+"introduction to" pages to give you a high-level overview and relevant links
+to help you navigate to the guides and other materials of most interest to you.
 
 Security
 ========
 
-:ref:`Our security section <explanation-security>` includes additional
-discussion of concepts and features around authentication, cryptography, and
-Virtual Private Networks (VPNs).
+:ref:`Our security explanations <explanation-security>` include high-level
+overviews of security configuration and good practices, and discussion of key
+concepts in the following topics:
+
+* **Authentication**, with introductions to Kerberos and SSSD
+* **Cryptography** and cryptographic libraries
+* **Virtual Private Networks (VPNs)** with introductions to WireGuard VPN and
+  its related concepts
+
+.. toctree::
+    :hidden:
+    :titlesonly:
 
-For more general introductions to these topics, see:
+    security.rst
 
-* :ref:`introduction-to-security`
-* :ref:`introduction-to-crypto-libraries`
-* :ref:`introduction-to-wireguard-vpn`
- 
 Networking
 ==========
 
-.. include:: networking.rst
-    :start-line: 4
-    :end-before: .. toctree::
+:ref:`Our networking section <explanation-networking>` will give you an
+introduction to networking and details on some of the key topics, such as:
+
+* **Network tooling and configuration**
+* **Network shares**
+
+.. toctree::
+    :hidden:
+    :titlesonly:
+
+    networking.rst
 
 Managing software
 =================
 
-.. include:: software.rst
-    :start-line: 4
-    :end-before: .. toctree::
+:ref:`Managing software <explanation-managing-software>` is an integral part of
+system maintenance.
+
+.. toctree::
+    :hidden:
+    :titlesonly:
+
+    software.rst
 
 Storage
 =======
 
-.. include:: storage.rst
-    :start-line: 4
-    :end-before: .. toctree::
+:ref:`In data and storage <explanation-data-and-storage>` we discuss:
+
+* **Managing data**
+* **Storage and backups**
+
+.. toctree::
+   :hidden:
+   :titlesonly:
+
+   data-and-storage.rst
 
 Web services
 ============
 
-.. include:: web-services.rst
-    :start-line: 4
-    :end-before: .. toctree::
+Our :ref:`explanation-web-services` section includes details about web servers
+and how they work, as well as related topics like Squid proxy servers.
+
+.. toctree::
+   :hidden:
+   :titlesonly:
+
+   web-services.rst
 
 Virtualisation and containers
 =============================
 
-.. include:: virtualisation.rst
-    :start-line: 4
-    :end-before: .. toctree::
+Our :ref:`Virtualisation and containers <explanation-virtualisation>` section
+includes overviews of the available virtualisation and container tooling in
+the Ubuntu space, as well as more detail about topics like rock images, Docker
+and more!
+
+.. toctree::
+   :hidden:
+   :titlesonly:
+
+   virtualisation.rst
 
 System tuning
 =============
 
-.. include:: performance.rst
-    :start-after: _end-system-tuning-intro:
-    :end-before: .. toctree::
+:ref:`Our system tuning <explanation-system-tuning>` section provides details
+on system performance and optimization, covering concepts like Profile-Guided
+Optimization (PGO) and some common tooling.
+
+.. toctree::
+    :hidden:
+    :titlesonly:
+
+    performance.rst
 
 High Availability
 =================
 
-.. include:: high-availability.rst
-    :start-line: 4
-    :end-before: .. toctree::
+:ref:`High Availability <explanation-high-availability>` is a method for
+clustering resources to ensure minimal downtime if a particular component fails.
+
+In this section we provide an introduction to High Availability and explain
+some of the key concepts.
 
 .. toctree::
     :hidden:
     :titlesonly:
 
-    introduction-to.rst
-    security.rst
-    networking.rst
-    software.rst
-    storage.rst
-    virtualisation.rst
-    web-services.rst
-    performance.rst
     high-availability.rst
 
+.. toctree::
+    :hidden:
+    :titlesonly:
+
+    introduction-to.rst
+

explanation/introduction-to.rst

@@ -11,39 +11,9 @@ help you navigate to the guides and other materials of most interest to you.
 
 * :ref:`Introduction to virtualization <introduction-to-virtualization>`
 
-**Networking**
-
-* :ref:`Introduction to networking <introduction-to-networking>`
-* :ref:`Introduction to Samba <introduction-to-samba>`
-* :ref:`Introduction to Active Directory integration <introduction-to-active-directory-integration>`
-* :ref:`Introduction to Device mapper multipathing <introduction-to-multipath>`
-
-
-**Authentication and access**
-
-* :ref:`Introduction to Kerberos <introduction-to-kerberos>`
-* :ref:`Introduction to SSSD <introduction-to-network-user-authentication-with-sssd>`
-* :ref:`Introduction to OpenLDAP <introduction-to-openldap>`
-
-
-**Security**
-
-* :ref:`Introduction to security <introduction-to-security>`
-* :ref:`Introduction to cryptographic libraries <introduction-to-crypto-libraries>`
-* :ref:`Introduction to WireGuard VPN <introduction-to-wireguard-vpn>`
-
-
 **Useful services**
 
 * :ref:`Introduction to mail servers <introduction-to-mail-services>`
-* :ref:`Introduction to web servers <introduction-to-web-servers>`
-* :ref:`Introduction to backups <introduction-to-backups>`
-* :ref:`Introduction to databases <introduction-to-databases>`
-
-
-**High Availability**
-
-* :ref:`Introduction to High Availability <introduction-to-high-availability>`
 
 **eBPF**
 
@@ -57,20 +27,7 @@ help you navigate to the guides and other materials of most interest to you.
     :hidden:
 
     Virtualization <intro-to/virtualisation>
-    Networking <intro-to/networking>
-    Samba <intro-to/samba>
-    Active Directory integration <intro-to/AD-integration>
-    Device mapper multipathing <intro-to/multipath>
-    Kerberos <intro-to/kerberos>
-    SSSD <intro-to/sssd>
-    OpenLDAP <intro-to/openldap>
-    Security <intro-to/security>
-    Cryptographic libraries <intro-to/crypto-libraries>
-    WireGuard VPN <intro-to/wireguard-vpn>
     Mail servers <intro-to/mail-services>
-    Web servers <intro-to/web-servers>
-    Backups <intro-to/backups>
-    Databases <intro-to/databases>
-    High Availability <intro-to/high-availability>
     eBPF <intro-to/ebpf>
     Cloud-init <intro-to/cloud-init>
+