Titles and LinkTitles

One of the most important components of a technical resource is its title.

For Chainguard Academy, there are actually two titles you need to consider:

• The title itself. This is the title that appears at the top of the resource's page and shows up in search engine results.
• The linkTitle. A linkTitle is a Hugo feature that allows you to define a shorter version of a page's title. If defined, this is what will appear in the left-hand navigation menu.

Both titles and linkTitles are defined in a resource's front matter. Here, we'll dig into best practices and guidelines for creating each.

Titles

Per the SEO Guidelines from Write the Docs, documentation should have "imperative, user-centric, goal-oriented headings." Likewise, a title should clearly convey the resource's purpose and goals using action-oriented language centered on the reader.

For example, a title like "Chainguard Widgets" might convey the overall subject of a documentation resource, but fails to provide clear context as to what a ready can accomplish by reading it.

A more goal-oriented and user-centric title might be something like "Implement Doodads with Chainguard Widgets." This example starts with an action verb ("implement") and by taking the imperative voice, it lets the reader know what they will learn to do and with what.

General guidelines for titles on Academy:

• Shorter is usually better, though not at the expense of clarity.
• For titles starting with "How to…", the "to" should not be capitalized.
  • We've not been consistent about this in the past. If you're updating an existing document that capitalizes "to" in the title, be sure to change it.
• Titles using the following formats are acceptable for procedural tutorials:
  • "Verb X with Y"
  • "Verbing X with Y"
  • "How to Verb X with Y"
• Conceptual and Reference articles don't need to be imperative. For example, "Overview of Chainguard Images" is clear enough for readers to understand what the article covers.
  • That said, you can still use titles like "Understanding Widgets" for conceptual articles if you so choose.

LinkTitles

LinkTitles require a different approach than regular titles as they don't affect SEO and are, by their nature, shorter. Additionally, the format used for a linkTitle depends on the type of resource.

Conceptual articles or documents that outline how to use a specific feature can have linkTitles that consist of a noun with one or more optional descriptors. For example:

• Images Directory
• CVE Visualizations
• Product Release Lifecycle

If it makes sense, these kinds of resources can also use linkTitles that are formed as a question or start with "How", like these:

• What is an SBOM?
• How Images are Tested

Meanwhile, procedural tutorials should start with a verb:

• Using Chainguard Images
• Retrieve an Image's SBOM
• Compare Images with chainctl

General guidelines for linkTitles on Academy:

• LinkTitles should always follow the title case.
• Ideally, linkTitles should be short enough to stay on one line
• To keep a linkTitle's length to a minimum, avoid using gerunds and instead use the present tense of the active verb
  • This is not a strict rule. For example, a linkTitle like "Understanding Widgets" would not be improved by shortening it to "Understand Widgets."
• It can get repetitive for the same word or phrase to appear in numerous linkTitles. Even specifying "Chainguard" in multiple linkTitles in the same section can feel redundant.