Skip to main content

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


Updated on January 21, 2021

Various media types make your content visually appealing. You can use a variety of visual aids that you can create in Snagit, Camtasia, or Loom to facilitate understanding, to keep the process or tutorial flow interesting, and to cater for the needs of users with different learning styles. Follow these guidelines to efficiently enrich your documents with meaningful visuals.

General guidelines

  • Use the word figure to refer to screenshots, diagrams, GIFs, and so on. For more information, see figure.
  • Add a 1pt black border for every figure.
  • Write a caption or title for every visual element.
  • Do not include images that do not add value. That is, do not use them to illustrate simple steps, obvious step results, or minor UI elements.
  • Do not add screenshots with empty fields. Show completed forms and selected parameters.
  • Do not expose internal names of users, files, rules, or companies. Use the Blur tool to hide that information.
  • For tutorials, follow the naming that you introduce in the use case across the entire tutorial.
  • Do not cut any UI elements. If you need to capture only part of the screen, ensure that the borders do not go through the text or any UI elements.
  • Remove any unnecessary parts of the screen, such as empty spaces, with the Cut Out tool.
  • Remember that visuals are there to support, not to replace, the steps.

DITA topics

Limit the use of images in topics. However, you can insert a graphic to facilitate understanding of a concept that you describe in a supertask, or to make a procedure easier to perform through visual examples.

Community articles

Images are best suited for Pega Community articles that cover full-scale use cases, examples, and feature tutorials. You can use various visual elements to make these articles interesting and more informative.

  • Requirements for image files

    Ensure that you name and save your image files correctly to avoid any processing errors.

  • Screenshots

    Use a screenshot to support an article, but do not rely only on screenshots or other visual media to document a procedure.

  • Diagrams

    Add diagrams to show a process flow, to identify the main UI elements of an application, or to illustrate complex concepts. When you create or update diagrams for your topics and articles, keep in mind the following considerations for Pega-compliant figures and art.

  • GIFs

    Use GIFs to provide examples for complicated steps, to illustrate tutorials, or to present features in What's New articles.

  • Process flows

    A process flow is a series of screenshots, optionally connected with arrows. Add a process flow to show a sequence of high-level steps in a process.

  • Wireframes

    Add wireframes to show a more conceptual representation of a UI or a process.

  • Developing featurette videos

    Add a featurette video to show a feature or tutorial in action.

  • Adding attachments

    Attach files to Community articles to provide additional resources, such as configuration files or samples.

  • Guidelines for writing alternative text

    When you include images in content, such as screenshots, diagrams, GIFs, or charts, ensure that you provide alternative (alt) text with the image.

  • Using Snagit

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. is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us