Here are some best practices to keep in mind when creating a topic:

Audience

Write for your audience. Address your audience as "you," but be clear about your target readership, and consider the following questions when creating your content:

• What is the role of your audience?
• What is the level of expertise of your audience?
• Is your audience selling a product, creating development plans, developing an application, troubleshooting an application, or learning how to use an application?

Audiences can overlap. For example, capabilities such as case management user experience apply to various business processes and workflows. As a best practice, make your content outcomes and structure suitable to the functionality that you describe and the type of content that you use; write for a global audience so that writing is clear, concise, and grammatically correct.

For more information, see Content for a global audience.

Content structure

Design the material to make it relevant and meaningful to the learner by relating what is being learned with what the learner already knows and will use on the job.

• Keep the material short, concise, and clear.
• Gain attention through relevant stories, facts, or questions.
• Chunk up the material into bite-sized, consumable pieces. For example, if you had 30 seconds to memorize ten numbers, which way is easier?  7-2-9-6-3-4-0-5-2-1 or 729-634-0521?
• Remember this fact: "...a user will remember 10% of what they read, 20% of what they hear, 30% of what they see, and 90% of what they do." (ref: Edgar Dale).  Be sure to add interactions, simulations, scenario-based testing, and quizzing to aid in the retention of the material.

Short descriptions

Always use a Text-only section to open your topics and include an introductory short description.

Short descriptions for concept topics

In a short description for a concept topic, focus on briefly defining the object or idea of the topic. You should also explain why it is important that users understand the concept.
A good short description for a concept topic answers at least one of the following questions:

• What is the concept or functionality that is described in the topic?
• What benefits does the functionality provide for the user?
• Why should users care about this concept or feature?

Short descriptions for task topics

In a short description for a task topic, focus on describing why the task is important, and how users can benefit from completing the task. Even though some benefits might seem obvious, always include the why information in your tasks.

Short descriptions for task topics do not provide any procedural information that belongs to the task. A good short description for a task topic answers at least one of the following questions:

• What is the goal for the users who perform the task?
• Why should users complete the task, and how can users benefit from doing it?
• How does the task fit with other related tasks?

Quotations and external references

Never use quotes in technically-oriented content. Keep quotes to a limit when writing marketing-oriented content.

• When you do use quotes in marketing-oriented content:
  • Keep the quote is concise
  • Reference only the part of the quote that is relevant (an ellipse is used for the irrelevant part of the quote)
  • Tie the information back to Pega in some way.
    For example: Forrester describes low-code development as "Products and/or cloud services for application development that employ visual, declarative techniques instead of programming…" This development is exactly what Pega has been doing for 30 years — creating Software That Writes Your Software™.
  • Do not use hyperlinks to external sites, as they can change. If you need to direct users to an external website for additional information, create a general cross-reference to the external source like the following example: For more information about the [topic], go to the [reference website/book/article/document]. For more information, see the Hyperlinks and cross-references section of the​ Technical Documentation Guidebook (VPN).