Skip to main content

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

Best practices

Updated on January 21, 2021

Apply the following best practices to create consistent and engaging technical documentation.

  • Content elements

    Answer the following questions to provide meaningful editor review feedback on specific fields and elements of technical documentation content.

  • Language and grammar

    When you review content, pay special attention to language and grammar.

  • Task topics

    When reviewing tasks, focus on the following areas:

  • Concept topics

    When reviewing concepts, focus on the following areas:

  • Reference topics

    When reviewing reference content, focus on the following areas:

  • Don't document the obvious

    Part of minimalist writing is to document only relevant information and to avoid stating the obvious.

  • Tone, voice, and terms to avoid

    In general, informal language and tone are acceptable; however, do not use contractions. We do ask that all team members strive for clear, consistent, and accurate information.

  • Creating clear and consistent content

    Create texts that are simple, clear, direct and informative. This is especially helpful to those whose native language is not English.

  • Guidelines for topic and article file names, titles, and locations

    DITA topics and Community articles are distinct content containers, each with a unique title and purpose. The title of a topic or article reflects the content type that they include. Additionally, because DITA help topics are opened directly from Pega Platform, they have restrictions on the file name and location.

  • Content for a global audience

    As a global software development firm, Pega creates products and documentation for an audience that includes our own worldwide sales force, as well as the various support teams and engineering labs that Pega maintains around the world. Therefore, we must ensure that all of our writing is clear, concise, and grammatically correct. Everyone then has a better chance of understanding our meaning, whether they are English native speakers, non-native speakers, translators and interpreters, or even translation software.

  • Good content practices

    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.

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