Titles and Headings

Titles, headings, and subheadings are a significant part of technical documentation as they communicate the logic of the presented content and form the spine of the article.

In This Article

• General
• Structure
• Levels
• Capitalization
• -ing Forms
• Style
• Knowledge Base Articles
• Frequently Asked Questions (FAQ) Articles
• Demos

General

• Titles, headings, and subheadings act as a concise table of contents for the topic.
• They help users find the right place to get the information they need.
• Titles, headings, and subheadings can also be referenced in support tickets and replies to customers through their anchors.

Structure

• Through the title, headings, and subheadings of an article you build its skeleton. The content under each title, heading, or subheading has to be logically structured in a meaningful way.
  
• At Progress, the title of the article and the title meta element are identical.
• For SEO purposes, the feature-specific meta_title (page_title in earlier versions) may differ from the meta title and, respectively, from the title of the article. For more information on how to structure the metadata block and what information to include, refer to the Style Guide article on metadata.

Levels

• Generally, HTML provides tags for nesting headings up to level six (<h1>-<h6>). Markdown provides corresponding heading level through the #-###### syntax.
• Depending on the website platform, which the specific Progress product documentation occupies, some sites provide visibility in the right side navigation up to level three. However, utilizing the available levels with meaningful internal structure is useful because anchors can still be referred to in support tickets.
  

• The title of the article corresponds to heading level one (<h1> in HTML, # in Markdown). You need to have a single instance of <h1> (#) within the same article.

  At Progress, some Knowledge Base articles, for example, do not need an explicitly stated title (<h1> or #) because it is automatically taken from the title property in the metadata. The technical implementation varies across the developer teams.

• The headings within the article correspond to <h2> in HTML or ## in Markdown.

• The subheadings within the article correspond to <h3> and <h4> in HTML, or ### and #### in Markdown.

Capitalization

The following guidelines apply to titles, meta_titles OR page_titles, and headings in the range <h1>-<h6>.

Always Capitalize

Never Capitalize

The first and last words within a heading. Nouns ("Widget"). Verbs ("Render", "Is"). Adjectives ("Interactive", "Comprehensive"). Adverbs ("Quickly", "Possibly"). Pronouns ("It", "Its"). Subordinating conjunctions ("If", "Because", "That"). All words in phrasal verbs ("Take Off", "Look After", "Turn Up"). Prepositions used as element names in the user interface ("The On Button"). The 1st and last word in a hyphenated expression ("How-To Guide", "Out-of-the-Box").

Coordinating conjunctions ("and", "but", "or"). Articles ("a", "an", "the"). Prepositions unless used as element names in the user interface ("at", "on", "between"). "To" when it is part of an infinitive ("Widgets to Beautify Your Mobile Applications").

The following table provides additional examples on the adopted practice of capitalizing titles.

Not that good	Much better
Adding the about Pull-Down Menu	Adding the About Pull-Down Menu
Running the In-browser Client	Running the In-Browser Client
Setting up Clicks and Routing	Setting Up Clicks and Routing
during Initialization	During Initialization
the Template Delegate	The Template Delegate
Possible To Port	Possible to Port

-ing Forms in Titles and Headings

For more information on using -ing forms (and Gerunds) in text, refer to the dedicated article.

While to avoid ambiguity it is not advisable to use -ing forms (and Gerunds) in text, -ing forms are usual and helpful in titles and headings when the article describes a procedure or explains how to do something. For example, "Getting Started", "Installing the Plugin", "Managing the Process", "Handing Off Projects to Developers", and so on.

Style

• Make all same-level headings grammatically parallel.

  Not that good	Much better
  Getting Started Some text. Initialization of the Grid Some text. Bind the Grid to Local Data Some text. Binding the Grid to Remote Data Some text.	Getting Started Some text. Initializing the Grid Some text. Binding the Grid to Local Data Some text. Binding the Grid to Remote Data Some text.

• Make sure you have at least two subheadings in a heading section.

  Not that good	Much better
  Reference Existing Instances Refer to an existing Grid instance by using the jQuery.data() method.	Telerik Platform Services Views Views (also Screen Builder) is a service for visual code-less development. Data, Users, Notifications, Business Logic The four basic backend services of the Telerik Platform let you focus on developing the frontend of your app in AppBuilder by providing you with cloud services.

• Use text between a heading and its subheading as that content indicates to users whether what follows is what they need. However, do not insert filler texts just to stick to this rule.

  Not that good	Much better
  Getting Started Read in Advance Because of the numerous functionalities it supports, the Grid is the most complex of the Kendo UI widgets so far.	System Requirements for the Package for Sublime Text Before installing and running the package for Sublime Text, verify that your system meets the following requirements. Software Requirements Windows, OS X Mavericks or Ubuntu 14.04 LTS Sublime Text 2 or Sublime Text 3

• If the table of contents (TOC) renders subheadings, do not repeat parts of the heading in the subheadings that follow it.

  Not that good	Much better
  Data Binding Some text. Local Data Binding Some text. Remote Data Binding Some text.	Data Binding Some text. Binding to Local Data Some text. Binding to Remote Data Some text.

• As long as the meaning is unambiguous, drop articles in titles, headings, and subheadings.

  Not that good	Much better
  Preserving the State in the Cookies	Preserving the State in Cookies

• If you include quotes in titles, follow the original capitalization of the quotes.

  Not that good	Much better
  Extending in "Pretty and Straightforward" Ways	Extending in "pretty and straightforward" Ways

• Do not use metaphors in titles, headings, and subheadings. They are not appropriate for official documentation.

  Not that good	Much better
  The "Right Way" to Add DataSource Instances	Proper Approaches to Add DataSource Instances

• In conceptual articles, do not cite object types, methods, events, and the like in titles, headings, and subheadings. Try to describe the user's goal or action. The only exception is when creating API references.

  Not that good	Much better
  animation Object Configuration	Configuring the Opening of Animations

• Do not use punctuation in a title. Commas are permitted but not recommended. Exceptions from this rule are acceptable only for Knowledge Base articles on troubleshooting.

  Not that good	Much better
  Get the Beta Now!	Get the Beta Now or Immediate Beta Version Download

Knowledge Base Articles

For more information, refer to the Style Guide topic on KB articles.

FAQ Articles

For more information, refer to the Style Guide topic on FAQ articles.

Demos

For more information, refer to the Style Guide topic on publishing Demos.