Media
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
Previous topic Additional style guidelines Next topic Requirements for image files