Skip to main content


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

Don't document the obvious

Updated on January 21, 2021

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

We've all seen the following kinds of examples:

  1. Enter your name in the Name field.
  2. Use the State/Province list to specify the state or province for the address.
Usually, this information is provided for "completeness;" not because it adds value. The thinking is that if you document one field, you have to document them all. At Pega, our minimalist writing guidelines say the opposite: if you can't come up with a good reason for documenting something, leave it out.

Example:

  1. Complete the fields in the User Information wizard.

    When you complete the Mailing preferences section of the wizard, be sure to specify values for postal, email, and carrier pigeon individually. The default value for all three fields is to not send mail to the user in keeping with many local Do Not Contact laws.

    The Attitude drop-down list provides a way to track the user's attitude during customer service interactions, such as Helpful, Polite, Cranky, or Atomic. You can accept or change the default setting specified in the wizard. Your representatives can also change this setting with each customer interaction.

In this example, only two sections of the wizard were worth mentioning, but not the user's name, address, shirt size, or other obvious data in the wizard.

Here are some criteria to use in deciding whether to document a field in a task:

  • Is it non-obvious? If you can't easily decide how to complete a particular field or section, the user is likely to have trouble, too. A field with a cryptic label needs further explanation (and a bug filed to rename the field).
  • Does it affect other steps in the task or product behavior elsewhere? For example, "Selecting the One-time Use check box prevents this user record from being stored, and deletes it from memory after the case is resolved" is important information to document. Or, it might be worth explaining that the user's first name and last name are used to automatically generate the Operator ID.
  • Does the user need guidance on how to choose an option (or a setting?) or to complete the information? For example, an Update frequency field that accepts values from 1 to 24 hours might need explanation... does a lower number affect system performance? Does a higher number cause the system to miss updates? If the user's choice might have implications later, for security, system performance, reporting ability, or other reasons, then you must provide the criteria that users must consider to make that choice wisely.

Use your best judgment in determining how obvious something is; accept guidance from your SME or product owner, of course, but the final decisions are yours as the writer. Cite (or refer to) this article to explain your decision, if necessary.

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.

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

Close Deprecation Notice
Contact us