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.
Previous topic Style Guide Next topic Content elements