Skip to main content


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

Content elements

Updated on January 21, 2021

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

Titles

  • Is the title appropriate for the type of content? Does the title start with the correct type of word:
    • Gerund for a task topic, Community tutorial, or procedure
    • Noun or noun phrase for a concept or reference topic
    • Noun or noun clause for a release note
    • Imperative for a What's New article
  • Is the title concise, accurate, and not too long? (Best practice is not to wrap to a second line.)
  • Does the title follow sentence-style capitalization?
  • If the content describes how to do a task, is the title user-oriented instead of product-oriented?
  • Are trademark symbols excluded from the title?
For example: For example:
  • Correct: Changing user profiles
  • Incorrect: Using the User Profile dialog box

Short descriptions

  • Is the short description brief (two to three sentences; about 50 words)?
  • For task information, does the short description state the purpose of the task and the benefit to the user? For conceptual or reference information, does the short description provide a context that helps users to understand the purpose and benefit of the topic content?
  • Does the short description end with a period and not a colon?
  • Does the short description include only text; no notes, bullets, tables, or figures?
For more information, see Short descriptions.
For example: For example:
  • You can configure a case type to skip the create view when you create a case. You can override the create view to speed up or simplify case creation.
  • You can display the data in a report definition by using a map, if the data supports this kind of visualization. For example, map charts are useful for reports on sales by region, activity by state, and incidents by county.
  • Use Pulse to communicate and collaborate with other users by sharing messages and files, tagging content, and referencing users. You can use Pulse in various contexts, such as within a case or as a conversation in your user profile.

Prerequisites

  • Do prerequisites start with an imperative verb?
  • For a set of prerequisites, are the prerequisite steps included in a list that is followed by an introductory sentence?
  • Do prerequisites provide links to tasks that describe how to complete them?

Body

  • Does the content flow logically from title to short description to main body of the help topic or article?
  • Is there no mixed content of different types, for example, steps buried in conceptual descriptions?
  • Have the correct heading levels been used?
  • For longer articles and help topics, have headings or section headings been used to structure the content?
  • Are any sentences too long? (~25 words maximum)

Steps in tasks

  • Remember to orient the user in the first step; provide information about the starting point. Do not assume that users read every topic in sequential order.
    • Correct: In the Source list, click Data Transform.
    • Incorrect: Click Data Transform in the Source list.
  • Is each step really a step, that is, does the step correspond to a user action and not to a user interface action?
    • Incorrect: 8. The Apply to (class) field and Add to ruleset field are filled out automatically.
  • Are optional steps formatted correctly?
    • Correct: 5. Optional: To exclude a case type from the import process, clear the check box next to the case type.
    • Incorrect: 5. Optionally, clear the check box next to a case type to exclude it from the import process.

Lists

  • Are list items parallel?
    • If one item begins with a verb or noun, all items must begin with a verb or noun.
  • Is the first word in each bullet capitalized?
  • Are numbers used only for information that must be read or followed in a sequence?
  • Does the list have an introductory sentence that ends with a colon?
  • Is the correct punctuation used? Use a period at the end of list items in the following cases:
    • When at least one bullet item is a complete sentence
    • When the bullets are a mix of sentence fragments and complete sentences
    • When the bullets complete the introductory sentence

Tables

  • Is the table easy to understand?
  • Is the formatting uncomplicated?
  • Does the table have an introductory sentence that ends with a colon?
  • Do the column headings use sentence-style capitalization?

Figures

  • Does the text before the figure describe the purpose of the figure?
  • Does the figure have a caption?
  • Is the figure caption a short noun phrase?
  • Does the figure have alt text? (both DITA and Community content)
  • Is the text in the figure legible?
  • Does the figure show only completed fields and selected options?
  • Is the text in the figure free from typos and outdated product names?
  • Are names of real people or companies blurred in the figure?
  • Does the figure show the UI without cutting through its elements or text?
  • Is there no excessive blank space or unnecessary parts of the UI visible in the figure?
  • Are the figures consistent in size?

Cross-references

  • Are cross-references formatted correctly and consistently?
    • For more information, see…
    • For more information about xyz, see…
    • To obtain a hotfix catalog, contact Global Client Support.
    • To define more fields, repeat steps 5 through 8.
    • For more information about EAR deployment and polling, see the Pega Community article Using MQ and JMS Services with Enterprise Application deployment.
  • In cross-references, is about used instead of on? (Microsoft Style)
  • Are there only general references to third-party documentation?
For example: For example: For information about the EFormUtils API, see the PublicAPI Javadoc documentation.

Links

  • In help topics, are inline links used sparingly, usually only to a related or prerequisite task?
  • In help topics, are the related links limited to the most closely related information? Do the links number more than 5 or 6?
  • For all content, do the links work? Is there any duplication between inline links and related content links?
  • Does the topic or article provide related information links at the bottom of the page?
  • Are there no links to external documentation?

Tags

Other

Have a question? Get answers now.

Visit the Support Center to ask questions, engage in discussions, share ideas, and help others.

Visit the Support Center

Did you find this content helpful?

Yes
No

Want to help us improve this content?
Suggest an edit

We'd prefer it if you saw us at our best.

Pega.com is not optimized for Internet Explorer. For the optimal experience, please use:

Close Deprecation Notice
Contact us