Metadata

To handle their projects in a fast and timely manner, users need to have great visibility over the online resources of the DevTools products. Therefore, it is of huge importance to better position the DevTools documentation and demo sites in search engine results by applying the metadata that works for their indexing.

While the guidelines in this article mainly target the documentation sites, when applicable, they are fully valid to the DevTools demos sites. For the specific requirements to the descriptive content of the demos, refer to the Style Guide article on publishing DveTools demos.

Guidelines

Implement a meta block in the <head> section of each article.

For SEO purposes and content indexing, include the following meta tags:

Meta element	Usage	Description
`title`	Mandatory	The title of the article displayed in the sidebar navigation.
`page_title`	Mandatory	The text that browsers display in the title bar for the corresponding tab or window (the `<title>` HTML element). Vital for SEO. If not defined, the title corresponds to the URL of the page. Recommended maximum length: 70. For more information, refer to the section on creating effective page titles.
`description`	Mandatory	The `<meta name="description" content="Sample Text">` element that Jekyll inserts in the `<head>` for your article page. Used for SEO. Insert a concise and descriptive sentence consisting of around 150 characters that explains what the article is about. If the length is more than 150 characters, search engines still read and use it for ranking. Minimum length: 100. The description is the text that is usually displayed to the users in their search results. Any words that correspond to words from the organic search are rendered to the user in bold.
`slug`	Mandatory	The unique identifier for each article that you can create yourself. It acts as a local URL within the repository. You can use it instead of relative or absolute URLs to create hyperlinks in your documentation. During build, Jekyll replaces the slug with its corresponding relative URL.
`position`	Optional	The number that indicates the position of the article in the current directory in the sidebar navigation. If not defined, Jekyll sorts the articles in the section in ascending alphabetical order.
`tags`	Optional	The list of relevant key words or phrases that describe the article content. Separate them with a comma. Use lower case for general terms. Preserve case for brands, trademarks, names, and other terms that have special casing. Currently, it is not possible for users to browse content by tag.
`previous_url`	If needed	A previous URL relative to the root that users can no longer access. Used to handle redirects. You can add multiple previous URLs, separated by a comma. Make sure to set proper redirects when you move or delete content to avoid SEO issues and user frustration.

Entries and Syntax

Depending on the type of article, the metadata entries may differ. For example, for a KB article, most often you have a ticket_id while that metadata entry will be unnecessary in a feature-specific article. However, most of the metadata entries DevTools use are must-haves.

The following example displays a possible way your metadata chunk may look like.

  ---
  title: Overview
  page_title: jQuery Grid Documentation - Data Grid Overview
  description: Try now the Kendo UI for jQuery Data Grid component covering everything from paging, sorting, filtering, editing, and grouping to exporting to PDF and Excel.
  tags: grid, jquery, kendoui, editing, grouping, filtering, sorting, paging
  previous_url: /web/grid/introduction
  slug: overview_kendoui_grid_widget
  position: 0
  ---

Creating Effective Meta Tags

Meta tags are best used when EXACTLY describing the page in question because, in this way, they help search engines to shortcut to the information about that page and quickly handle informational queries.

When creating meta tags, consider the following recommendations:

Create accurate, relevant, and descriptive meta tags.
Do not unnecessarily focus them on a single keyword.
First think about what the "topic" and "concept" of a page is, what "purpose" it serves, and what kind of end "user experience" it targets. Only then you have to think about "meta tags".
If you are optimizing the content for Google, think in terms of "topic" or "subject", or information "hub", and not in terms of "page" or "article".
All major search engines recommend the sensible use of metadata. If you’re writing useful, descriptive tags, it will be unlikely any major search engine will penalize their use.
Most search engines use or have used meta information in some way to help classify a document. However, just because a search engine "uses", for example, meta-description tags, doesn’t mean they are using it as a positive ranking signal where your page ranks in the Search Engine Result Pages (SERPs).

Creating Effective Meta Page Titles

The page_title metadata entry in the front matter is one of the most significant pieces of metadata as this is what the user sees on hovering over the tab of the page. Therefore, it is mandatory for the page_title to contain the full context of the article and the name of the component.

In the DevTools documentation, page titles consist of two or more parts, which may include, for example, section + component + product. Depending on the preference of the product team, these sections can be implemented either manually or generated automatically based on templates, or by utilizing a combined approach. Whatever the workflow, divide the page_title parts by using a dash (-) as semantically, dashes are treated by search engines as and.

Note that Google truncates the page_title content after a specific number of symbols. Therefore, you have to place the context of the article at the beginning of the page_title and leave the name of the component to its end.

To be on the safe side and solve possible page_title issues, it is recommended that you approach the case in a strategic and sustainable way:

Consider contacting the SEO team and agreeing on general recommendations and/or a template for the page_title content, for example, Grid Data Binding - Kendo UI for jQuery by Progress.

For feature-specific topics (for example, Data Virtualization of the DropDownList), the SEO team can provide keywords and recommend where to place them—whether at the beginning or towards the end of the page_title. You may need to leave some of the content for the description entry.
Consider implementing a page_title template automatically so that misinterpretations and "creative writing" in the page_title are avoided.

For example, you may create a template rule that will generate the page_title based on the title rendered in the sidebar navigation, then add the name of the component and/or product, and then the name of the company.

The final template layout will depend on the latest information about the way the search engines parse information from the metadata chunk.

Creating Effective Meta Descriptions

The meta description of a page is typically displayed below the page link in the search results generated by a search engine. It serves as your initial opportunity to capture the user's attention. Engaging and relevant meta descriptions substantially enhance the likelihood that the user will click and explore the article. On the other hand, vague, irrelevant, and brief descriptions are often overlooked by search engines, which then favor other pieces of text that provide a better representation of the article.

To create an effective meta description:

Describe the content of the article accurately. Be specific. Don't use vague, templated, and nothing-saying expressions.
Make the text engaging by using action verbs like "learn", "discover", "explore", "master", "try", and so on.
Don't use filler words just to make the description 150 symbols long.
Make every word count. Don't use expressions that don't add value, for example, "Read more in Telerik UI for [Product] documentation."
Write the description when the article is complete—you will have plenty of text that you can summarize in the description.

Not that good	Much better
Data Binding appointments in the Scheduler for Blazor. Read more in Telerik UI for Blazor Documentation.	Learn how to bind the Scheduler for Blazor to a collection of appointments and explore the examples that demonstrate two different appointment models.

Demos

For more information, refer to the dedicated Style Guide article about the metadata and descriptive content of DevTools demos.