From d31ced8f4b0554368bf07c3337710ab4ecd9abc0 Mon Sep 17 00:00:00 2001
From: Clinton Fung <clinton.fung@canonical.com>
Date: Thu, 25 Apr 2024 18:34:33 +0200
Subject: [PATCH] Amend headings Re-group how-to's Add an introductory sentence
 per category Re-order list items Add a linkcheck_ignore item for
 www.breezy-vcs.org which is not reachable.

---
 custom_conf.py   |  1 +
 how-to/index.rst | 56 +++++++++++++++++++++++++-----------------------
 2 files changed, 30 insertions(+), 27 deletions(-)

diff --git a/custom_conf.py b/custom_conf.py
index 379317e..209472d 100644
--- a/custom_conf.py
+++ b/custom_conf.py
@@ -115,6 +115,7 @@
     'https://archive.ph/CAqQm',  # ignore, as works in browser, but link checker has some issues
     'https://bazaar.launchpad.net/lp-production-config',  # private
     'https://bazaar.staging.launchpad.net',  # broken, unclear why XXX 2023-10-14: jugmac00- check with team
+    'https://www.breezy-vcs.org', # broken, returns "Connection refused" on port 443
     'https://bugs.launchpad.net/charm-launchpad-buildd-image-modifier',  # private
     'https://bugs.launchpad.net/launchpad-vbuilder-manage',  # private
     'http://example.com/.*',  # ignore, example links
diff --git a/how-to/index.rst b/how-to/index.rst
index baf5f3d..4fe0228 100644
--- a/how-to/index.rst
+++ b/how-to/index.rst
@@ -4,6 +4,8 @@ How-to Guides
 Getting started
 ---------------
 
+To get started with Launchpad, get the source code and run a local development instance.
+
 .. toctree::
    :maxdepth: 1
 
@@ -14,48 +16,48 @@ Getting started
 Common development tasks
 ------------------------
 
+Once you have an instance of Launchpad, you're ready to contribute!
+
 .. toctree::
    :maxdepth: 1
 
+   submitting-a-patch
    fixing-bugs
    contributing-changes
-   submitting-a-patch
-   exceptions
-   security
-   using-breakpoints
-   preserve-query-count
-   land-update-for-loggerhead
-   update-configuration-for-testing
-   testing-scripts
-   create-job-publish-artifact
-   chameleon
+   use-updated-dependency
    database-schema-changes-process
+   apply-schema-changes
+   importing-an-ubuntu-package
 
-Common operational tasks
-------------------------
-
-.. toctree::
-   :maxdepth: 1
-
-   triage-bugs
+Launchpad development tips
+--------------------------
 
-Operating development instances
--------------------------------
+There are some things that can make your journey of contributing to Launchpad much easier.
 
 .. toctree::
    :maxdepth: 1
 
-   new-user
-   apply-schema-changes
-   use-updated-dependency
-   importing-an-ubuntu-package
+   update-configuration-for-testing
+   using-breakpoints
+   security
+   testing-scripts
+   exceptions
+   preserve-query-count
+   chameleon
 
-Operating Canonical's instances
--------------------------------
+Operating Launchpad
+------------------------
+
+If you have a running instance of Launchpad, there are common tasks you might need to perform.
 
 .. toctree::
    :maxdepth: 1
 
-   deploying-configuration-changes
-   checking-availability-of-launchpad-frontends
    getting-overview-of-build-farm
+   checking-availability-of-launchpad-frontends
+   new-user
+   create-job-publish-artifact
+   triage-bugs
+   deploying-configuration-changes
+   land-update-for-loggerhead
+