Capitalization

Use sentence-style capitalization for titles and all headings, regardless of level (applies to help topics, release notes (RNs), What's New articles (WNs), PDF guides, and so on), and consider the following points:

• Use sentence-style capitalization, which is easier for English-speakers of all levels and abilities to read and for machine translation software to translate.

  For more information about writing clearer text that is understandable by English speakers of differing levels, see Content for a global audience.

• Do not capitalize conjunctions, articles, or prepositions of fewer than four characters.
• Capitalize proper names as they are normally capitalized.

Punctuation

Correct use of punctuation is important to creating readable, comprehensible text. Some of the most common potential issues with punctuation in titles involve dashes and colons. Consider the following guidance:

• Avoid using dashes in titles.
• Do not use a colon at the end of a procedure heading.
• If a title contains a colon, use uppercase for the word after the colon.

Word order

If the choice and order of words in a title or heading are grammatically incorrect, ambiguous, or vague, users might skip reading essential content. Consider the following points when you formulate a title:

• Titles should contain the distinguishing information at the start and less important or repetitive information at the end.
• The first words of a good title should contain the important information or keywords, so that users can easily spot the information when they browse a table of contents.

  Good: Analyzing system-wide usage by using the Log-Usage class

  Bad: How to analyze system-wide usage with the Log-Usage class

• In some contexts, such as on a mobile device or in a navigation pane, titles can be truncated and become vague or ambiguous, so do not waste those first words. For example, task topic titles that start with How to waste valuable space with words that are repeated many times. Instead, start with the verb that defines the goal of the task or the important keyword for the concept or reference topic.

Length

Long-winded titles and headings look bad and risk becoming incomprehensible. Similarly, titles that are too short might not convey enough, or the right, information. To strike a balance in the length of your titles, apply the following guidelines:

• Provide enough information, but do not attempt to summarize the topic in the title; focus on the main point.
• Think in terms of progressive disclosure throughout the length of the article: title > short description > topic. In other words, you do not need to explain everything in the title because users will discover each part of the process in a logical way, as they read through the text.

Clarity

You can further improve the overall clarity of a title or heading by observing these guidelines:

• Be careful with words that end in -ing to avoid dangling modifiers.

  Ambiguous –ing + noun constructions occur much more frequently in headings and titles (including titles of windows and dialog boxes) than in running text.

• Avoid phrasing titles as questions.
• Ensure that the title accurately describes both the type of content and the content itself.

Wording

The wording of titles and headings has a direct effect on their clarity and accuracy. Choose your words carefully, according to the following guidelines:

• Make your titles accurate.

  The accuracy of a title or heading is the measure of how closely the title reflects the content of the article or topic. Inaccurate titles can mislead and frustrate users.

• Do not begin titles with About,Understanding, or How to. Be especially careful with the word using, which is less specific than other verbs and is frequently ambiguous. Often, using obscures the real task or user goal.

Abbreviations, trademark and special characters, and symbols

• Include only well-known abbreviations in titles, for example UI or HTTP.
• Do not abbreviate unnecessarily. For example, write database instead of DB.
• Do not use the ampersand (&) in place of the word and.
• Do not include trademark symbols in titles.

Nouns and gerunds

At Pega, we use a system of noun and gerund (verb) usage depending on the topic type: nouns and noun phrases for reference and child-level concept topic titles, and gerunds for tasks and parent-level concept titles.

The content of the title should give users a hint that the topic describes conceptual or reference information, for example:

For more details about identifying content type in titles by noun, gerund, and imperative, see Guidelines for topic and article file names, titles, and locations.

Summary

The key goals for writing a good title are as follows:

• Use sentence-style capitalization.
• Lead with the most important words.
• Keep titles short but descriptive.
• Take extra care with punctuation marks.
• Do not abbreviate unnecessarily.
• Make titles unique (helps in search results).
• Avoid ambiguous words and phrasing.