Add a page meta description

Search engines present options for the user to consider. Each search result contains at minimum the page’s title, snippet, and icon. From these elements, the user chooses what pages to visit.

A meta description is a short summary that search engines often reuse for the search result’s snippet. Since the meta description helps the user decide in advance whether a page contains what they seek, it has a direct impact on whether the user visits our documentation. Therefore, all new pages in a product’s documentation must include a meta description.

Format a meta description

At the top of a page, add this structure:

.. meta::
    :description: <description>

The meta description must be one line, because Sphinx options don’t support line breaks.

Write a meta description

Write the meta description after the page is written. The meta description is a reflection of what’s actually on the page, not what the page aspires to be.

Start with the Diátaxis category or action, such as How to or Reference for. Next, describe what the user will find on the page. Reuse text from the page itself where it’s appropriate.

Include a focus term or phrase, the key string that users are likely to search for. It can be a single word like security, or a short phrase such as create an Ubuntu Core image. Prefer widely recognized terminology. If your product isn’t yet well known, then it’s safer to use terms familiar to a global technical audience over product-specific ones.

Make every word count. There is no hard minimum length, but it should be longer and more descriptive than the title, and it should not merely repeat the wording of the title. The maximum length is 160 characters, because search engines truncate the snippet after 160 characters. This includes spaces.

For pages with the same format, share descriptions between them. For example, use the same meta description for every page of release notes, but change the version number.

Avoid these mistakes

Avoid calls to action like find, discover, explore, or read. These are so overused that they have become noise words. The user’s needs and actions in the moment are out of your control; the snippet should be a glimpse of the information on the page. Tutorials are the exception, where learn is appropriate.

Avoid qualities or claims about the product and its features, like simple, easy, or best-in-class. Marketing rhetoric, sales pitches, and business clichés like the following aren’t appropriate for documentation:

Don’t just write code; deliver a product. Start your journey today and turn your project into a production-ready, evergreen, blazing-fast, full-stack app.

Examples

For the Craft a snap tutorial in Snapcraft:

Learn the essentials of Snapcraft. In this tutorial, we package a small Python app into a snap.

For the how-to guide Change from core24 to core26 in Snapcraft:

How to migrate a snap from core24 to core26.

For the GNOME extension reference in Snapcraft:

Reference documentation for the GNOME extension, which adds the components for desktop apps that require GTK 3, GNOME 42 and higher, and GLib.

For the Parts lifecycle explanation in Snapcraft:

Explanation of the build process of a part in Snapcraft, with a breakdown of the individual steps and the effect each has on the snap filesystem.