Skip to content

Adopt a standard for docs page meta descriptions #377

@ptgott

Description

@ptgott

Docs pages are inconsistent in how they use meta descriptions, the description frontmatter field of a page. The internal Teleport documentation style guide recommends the following:

The description should be a sentence that starts with a verb, summarizes the content of the topic, and ends with a period.

At the same time, docs pages often use sentence fragments or sentences that do not begin with a verb.

Meanwhile, Google usually generates search result descriptions based on the page content, and only uses the meta description if it judges the description to be "better" (Google search docs). For the most part, the meta description isn't what users see when they view Teleport docs listed in search results.

Let's come up with a consistent standard for meta descriptions that:

  • We can lint automatically to ensure consistency
  • Is reasonable for search results and other uses of the meta description

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions