Skip to main content


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

Good content practices

Updated on January 21, 2021

When you develop your content, always have the user in mind. Follow these simple techniques to ensure that your content is informative, easy to read, and visually appealing at the same time.

Apply these good practices whenever they are appropriate to the functionality that you describe and the type of content that you use. For example, while following a sample scenario through various steps of the process for creating a strategy might make the entire flow easier to understand and apply in other scenarios, that technique might prove useless in a set of articles that outline the testing environment structure. Use these guidelines as pieces of advice about making your content better.

For a sample set of articles that put these guidelines into practice, see Creating a microjourney for customer success.

Outcome-oriented approach

Develop content that is focused on the user and the business objective by following these guidelines:

  • In parent topics, provide enough background information to allow the reader to make an informed decision whether to read on or not. Provide all the necessary detail upfront, so that users are equipped with sufficient knowledge before they perform the tasks. For more information, see Concept topics.
  • In every topic, use the short description to describe why the reader might want to read that content in the first place. Always describe what the users can accomplish through that content. For more information, see Short descriptions.
  • Enrich your topics with examples that illustrate how users can benefit from a given task or concept. For more information, see Fictitious information in examples in text, images, and code examples.
  • Ensure that your content is build around a common sample scenario. Once you describe a sample scenario in the parent topic, use this example throughout the children topics to describe different concepts.
    Note: Be careful not to limit your steps and descriptions to cover only the sample scenario alone. Instead, describe all the relevant configuration options that users can adjust to their individual needs. Use the sample scenario only to describe a real-life implementation of a given feature, but include steps for all supported configurations. This limitation does not apply to tutorials, which provide steps for only a specific scenario.

Structure

Provide our readers with a documentation journey that is easy to follow through the following strategies:

  • Treat every individual topic as a stand-alone part of a larger whole. Restate some of the information that has already been mentioned in other topics, though with a different level of detail. Always ensure that users know the context of performing a task.
  • For conceptual information that is a few paragraphs long, divide the content into meaningful sections with headers.
  • Enrich your content with images. Use screenshots, diagrams, process flows, GIFs, and so on.
    Note: Do not include images that do not add value. For example, do not add a screenshot just to show where a field is or how a landing page looks.
    For more information, see Media.

Navigation

Create uninterrupted navigation through a set of related topics, for example, children of a supertask, by applying the following practices:

  • In parent topics, define automatic map links so that all the children and their short descriptions are listed below the topic. Add a sentence that introduces that list to clearly describe whether the user has to complete all of the tasks or just some of them.
    Note: Do not use the related-links element to list children topics. Use this tag only to list additional reading on similar topics that might be of interest to the user.
    For more information, see TBD.
  • For sequences of tasks that are part of a journey, build connections between these tasks by adding pre- and postrequisites with links. Apply the rules that you use for steps, for example, use imperatives and focus on the outcome and business value. For more information, see Content elements.

  • Topic elements cheat sheet

    Review the following diagrams to ensure that your topics and articles contain the key elements that help us deliver coherent content across different capabilities.

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