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.
Topic or article type | Title format | Rules | Examples |
---|---|---|---|
Task | gerund | Focus on the action, not the tool. Use plural nouns unless the object that you mention is a unique one or you can change only one such item in a single task. Do not use about, or how to. |
|
Concept - parent (1st outline level) | gerund | Focus on what users can learn, starting the title with such gerunds
as understanding, learning about, or exploring. |
|
Concept - child (2nd and additional outline levels) | noun or noun phrase | Focus on what users can learn. Do not use overview. |
|
Reference | noun or noun phrase | Focus on what users might need to look up. |
|
Release note | noun, noun phrase, or clause | Focus on what has changed in terms of functionality. |
|
What's New | imperative | Focus on what users can achieve (business value). Add the release number in parentheses. |
|
Glossary | term name | Use lowercase for common words, and match spelling for industry terms, and abbreviations. |
|
Previous topic Creating clear and consistent content Next topic Content for a global audience