docs: add anchors and fix a few small things

docs/howto/index.rst

@@ -6,9 +6,9 @@ How-to guides
 .. toctree::
    :maxdepth: 2
 
-   set-up-charmcraft
+   manage-charmcraft
    manage-charms
-   manage-a-12-factor-app-charm
+   manage-12-factor-app-charms
    manage-extensions
    manage-resources
    manage-libraries

docs/howto/manage-a-12-factor-app-charm.rst → docs/howto/manage-12-factor-app-charms.rst

@@ -1,10 +1,10 @@
-.. _manage-a-12-factor-app-charm:
+.. _manage-12-factor-app-charms:
 
 
-Manage a 12-factor app charm
-============================
+Manage 12-factor app charms
+===========================
 
-    See also: :external+juju:ref:`Juju | Charm <charm>`
+    See also: :external+juju:ref:`Juju | Charm taxonomy <charm-taxonomy>`
 
 
 Prepare an OCI image for a 12-factor app charm

docs/howto/manage-channels.rst

@@ -3,6 +3,7 @@
 Manage channels
 ===============
 
+    See first: :external+juju:ref:`Juju | Charm channel <charm-channel>`
 
 Create a channel
 ----------------

docs/howto/set-up-charmcraft.rst → docs/howto/manage-charmcraft.rst

@@ -1,6 +1,6 @@
-.. _set-up-charmcraft:
+.. _manage-charmcraft:
 
-Set up Charmcraft
+Manage Charmcraft
 =================
 
 
@@ -148,3 +148,18 @@ To check the installed version, run:
 ..
 
     See more: :ref:`ref_commands_version`
+
+
+Upgrade Charmcraft
+------------------
+
+If you've installed Charmcraft on Linux as a snap, it will upgrade automatically.
+
+Uninstall Charmcraft
+--------------------
+
+For an installation on Linux via snap, run:
+
+.. code-block:: bash
+
+    sudo snap remove charmcraft

docs/howto/manage-charms.rst

@@ -6,10 +6,16 @@ Manage charms
     See first: :external+juju:ref:`Juju | Charm <charm>`,
     :external+juju:ref:`Juju | Manage charms <manage-charms>`
 
+.. _initialise-a-charm:
 
 Initialise a charm
 ------------------
 
+.. note::
+
+    **Best practice:** If you're setting up a git repository: Name it on the pattern
+     ``<charm name>-operator``. For the charm name, see :ref:`specify-a-name`.
+
 To initialise a charm project, create a directory for your charm, enter it, then run
 ``charmcraft init`` with the ``--profile`` flag followed by a suitable profile name (for
 machine charms: ``machine``; for Kubernetes charms: ``kubernetes``, ``simple``, or
@@ -74,10 +80,24 @@ To specify that the project is a charm (as supposed to a bundle), in your
 
     type: charm
 
+..
+
+    See more: :ref:`recipe-key-type`
+
+.. _specify-a-name:
 
 Specify a name
 ~~~~~~~~~~~~~~
 
+.. note::
+
+    **Best practice:** The name should be slug-oriented (ASCII lowercase letters,
+    numbers, and hyphens) and follow the pattern
+    ``<workload name in full>[<function>][-k8s]``. E.g., ``argo-server-k8s``.
+
+.. Need to add more content based on https://discourse.charmhub.io/t/charm-naming-guidelines/5364 .
+
+
 To specify a pack-and-deploy name for your charm, in your charm's
 ``charmcraft.yaml`` file specify the ``name`` key. E.g.,
 
@@ -210,9 +230,10 @@ charm's ``charmcraft.yaml`` file specify an item under the :ref:`links.website
 
     See more: :ref:`recipe-key-links`
 
+.. _add-docs:
 
-Add docs and a link to the docs
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Add docs
+~~~~~~~~
 
 If you publish your charm on Charmhub, reference documentation about the charm's
 resources, actions, configurations, relations, and libraries is extracted automatically.
@@ -251,7 +272,7 @@ value for the ``terms`` key. E.g.,
 Add an icon
 ~~~~~~~~~~~
 
-    See :ref:`manage-icons`.
+    See more: :ref:`manage-icons`
 
 
 Add runtime details to a charm
@@ -357,9 +378,10 @@ To specify device requirements, in your charm's ``charmcraft.yaml`` file specify
 
     See more: :ref:`recipe-key-devices`
 
+.. _manage-storage:
 
-Specify storage requirements
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Manage storage
+~~~~~~~~~~~~~~
 
 To specify storage requirements, in your charm's ``charmcraft.yaml`` file specify
 the ``storage`` key.
@@ -385,6 +407,7 @@ same machine as another charm, called its *principal*), in your charm's
 
     See more: :ref:`recipe-key-subordinate`
 
+.. _manage-actions:
 
 Manage actions
 ~~~~~~~~~~~~~~
@@ -399,6 +422,7 @@ specify the ``actions`` key.
 
     See next: :external+ops:ref:`manage-actions`
 
+.. _manage-configurations:
 
 Manage configurations
 ~~~~~~~~~~~~~~~~~~~~~
@@ -416,9 +440,10 @@ specify the ``config`` key.
 
     See next: :external+ops:ref:`manage-configurations`
 
+.. _manage-relations:
 
-Manage relations (integrations)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Manage relations
+~~~~~~~~~~~~~~~~
 
     See first: :external+juju:ref:`Juju | Relation <relation>`,
     :external+juju:ref:`Juju | Manage relations <manage-relations>`
@@ -434,10 +459,9 @@ Manage relations (integrations)
 Specify necessary libs
 ~~~~~~~~~~~~~~~~~~~~~~
 
-..    See first: `Juju | Library <>`_
-
     See more: :ref:`manage-libraries`
 
+.. _manage-secrets:
 
 Manage secrets
 ~~~~~~~~~~~~~~
@@ -459,6 +483,7 @@ Specify necessary parts
 
     See more: :ref:`manage-parts`
 
+.. _pack-a-charm:
 
 Pack a charm
 ------------
@@ -563,7 +588,7 @@ Publish a charm on Charmhub
 
        charmcraft login
 
-    ..
+..
 
    See more: :ref:`manage-the-current-charmhub-user`
 

docs/howto/manage-tracks.rst

@@ -3,7 +3,7 @@
 Manage tracks
 =============
 
-..    See also: :ref:`track` Add link to Juju docs > charm > channel > track
+    See first: :external+juju:ref:`Juju | Charm channel track <charm-channel-track>`
 
 When you register a charm name on Charmhub, you automatically get 4 channels, all with
 track ``latest``. However, as your charm evolves, you'll likely want to customise the
@@ -16,7 +16,8 @@ new pattern. This document shows you how.
 Request a track guardrail
 -------------------------
 
-..    See also: :ref:`guardrail` (link to new Juju docs > charm > channel > track > guardrail)
+    See first: :external+juju:ref:`Juju | Charm channel track guardrail
+    <charm-channel-track-guardrail>`
 
 To request a track guardrail, contact a Charmhub admin by creating a post on Discourse
 under the **charmhub requests** category, that is, here: