Skip to main content


         This documentation site is for previous versions. Visit our new documentation site for current releases.      
 

Titles

Updated on January 21, 2021

Titles give the essence of the information that the user is about to digest. Creating effective titles for help topics, articles, or headings is a key part of our job.

Consider the many ways in which we use titles in our own work with technical documentation:

  • Topic titles
  • Tables of contents
  • Search results
  • Links

(For similar reasons, this is why we must also write different opening lines for related What's New articles and release notes.)

When you write titles, apply the following basic guidelines and additional considerations:
  • Capitalization
  • Punctuation
  • Word order
  • Length
  • Clarity
  • Wording
  • Abbreviations, trademarks, special characters, and symbols
  • Nouns and gerunds

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.
For example:

Good: Processing data flows

Good: Getting started with Prediction Studio

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.
For example:
  • Good: Decision Management: Adjusting your decisions
  • Good: Decision Management: Rules for next best actions
  • Bad: Apache Cassandra - your friend and mine

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.
For example:

Good (clear): Changing the flow shapes in a decision tree

Bad (vague): How to change the flow shapes in a decision tree

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.
For example:

Good: Configuring rows in offline dynamic layouts

Bad: Adding and deleting rows in an offline repeating dynamic layout using the Pega API

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.
For example:
AmbiguousClearer
Tracking softwarePublishers of manuscript-tracking software
Editing optionsOptions for editing
Encoding namesNames of character encodings
UpgradesObtaining upgrades for your software

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.
For example:

Good: Diagnosing your system with the Performance tool

Good: DDS nodes in offline environments

Bad: Using the Performance tool

Bad: Understanding DDS nodes in an external environment

Abbreviations, trademark and special characters, and symbols

Apply the following guidelines for abbreviations, trademarks, 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.
For example:
  • Good: Direct Capture of Objectives and sales data
  • Good: Configuring a dynamic UI
  • Bad: DCO compatibility and sales data

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:

ConceptTaskReference
User rolesCreating user rolesSupported user roles
DatabasesConfiguring databasesDatabase types
DatabasesMonitoring databasesDatabase monitoring commands

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.

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Did you find this content helpful?

Want to help us improve this content?

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us