Charmcraft: Redo in-page links

[medubelko]

Background

The Charmcraft docs have a pattern of linking to other pages in block quotes:

  See also: `title <link>`_

Or See also sections:

.. seealso::

  `Product | title <link>`_

We'd like to shift away from a pattern of single-link blocks in the flow of the document.

Request

For non-index pages, reconsider each link in this format. If it doesn't fit, remove it from the page. If it does, make it flow into the page's main text. Indexes can be left as-is. They often have bare links, typically in lists.

Guidelines

Before you begin, review the Charmcraft contribution guidelines.

How to think about links

Canonical docs are written in naturally-flowing, plain English. Whenever a link appears in the text, carefully consider:

• How it fits into the context of the preceding discussion. Does the text naturally lead to this link? Does it feel like it belongs? If you were having a conversation with a friend, and they pushed their phone up to your face without warning, it would be quite rude! That's what an unexpected link feels like on the page.
• What benefit the reader gets from the link. A link is a call to action. But there are many actions the user could take in a document, including skipping your link. Does the link's text, and the text surrounding it, help the reader decide whether to click on it?
• If you start writing "See [link] for more details", don't! That sentence is no help to users. Instead, consider how to invite, or call, the reader to click on the link.

Examples

A general link to another site:

Discuss your ideas on the `Snapcraft forum <https://forum.snapcraft.io>`_.

Directing the user to follow a step in another guide:

First, `install Brew <https://brew.sh#install>`_.

Pointing the reader to a different page within the same docs:

To incorporate retrieved package information correctly, point ``adopt-info`` to the part
that runs ``craftctl set``. Without such a connection, the snap fails to build. You can
find more guidance on sourcing information in :ref:`reference-external-package-information`.

Pointing the reader to another documentation set:

The ``snap`` command itself has many diagnostic features that can help with debugging
runtime and configuration errors. `Debugging snaps <https://snapcraft.io/docs/debug-snaps>`_
in the snapd documentation covers how and when to use them.

[activus-d]

@medubelko I'd like to work on this issue.