Editing Checklist for Public Descriptions

What Is a Public Description (PD)?

A public description (PD) is a short informative message that contains key details for partners, customers, and the Acumatica Support team. It may describe either of the following:

A bug, which is an issue in the system related to incorrect functionality or a UI defect. The work on a bug is recorded in a Jira bug.
A product change, which is a new change or enhancement in the system. The work on a product change is recorded in a Jira CR (change request).

Sometimes the work on a bug or a product change is recorded in a Jira epic (and very rarely in other Jira issues, such as tasks or stories). In this case, before writing the PD, you should determine the type of the changes that were made in the system and recorded in the Jira issue:

If a system defect has been fixed, you should prepare the PD for a Jira bug.
If an enhancement or change to the functionality has been introduced, you should prepare the PD for a Jira CR.

Checklist: PD Contents

Product Change

1	The PD has only the applicable parts: Change Description: REQUIRED: Change Description OPTIONAL: Affected User Scenarios

2	The Change Description answers the applicable questions: What new functionality has been introduced? What functionality has been changed, and how does it work compared to the previous version or update? What capabilities are no longer available?

3	The Affected User Scenarios (if the product change has this part) answer this question: After the implementation of the enhancement, what actions, capabilities, or scenarios are available to users?

4	The product change is described in the present tense.

Checklist: Style and Grammar

Unnecessary part names have been removed from the PD:

“Bug or Change Description”
- “Bug Preconditions (if applicable)”
- “Affected User Scenarios (if applicable)”
- “Bug Description or Change Description (required)”
“Workaround (if applicable)”: Remove “(if applicable)” if the PD has a workaround.
“Fix Description (if applicable)”: Remove “(if applicable)” if the PD has a Fix Description.

2	Most sentences in the PD are shorter than 30 words (highly recommended), with a limit of 35 words. Split a long sentence into multiple shorter sentences, and use lists.

If the PD has many details of a particular type (such as settings or user actions), lists are used to make the PD more readable.

Click to view some examples

AC-244759: On the Late Assignment (AM312000) form, the lot or serial number of a material remained in the Unallocated Components table if both of the following were true:

The Allow Preassigning Lot/Serial Numbers check box was selected on the Production Order Maintenance (AM201500) form.
A negative material transaction was released for lot- or serial-tracked materials with an established parent-child relationship.

Also, on the Production Order Maintenance form, if On Completion was selected in the Require Parent/Lot Serial Number box, the final move transaction could not be released. The following error message was shown: The production order contains materials to which parent lot or serial numbers have not been assigned.

AC-236866: On the Dashboards (SM208600) form, an error occurred if a user performed the following steps:

Selecting the Make Visible on the UI check box for a dashboard
Defining the access rights on the Visible To tab
Copying and pasting this dashboard
For the created dashboard, selecting the Make Visible on the UI check box
Trying to save the created dashboard

The following error message was shown: Another process has added the ‘RolesInGraph’ record. Your changes will be lost.

4	The following rules apply to mentions of forms in Acumatica ERP: The word “form” is used (not “screen”). Form names are correct, including whether the name ends with an “s”: the Customers (AR303000) form, the Sales Orders (SO301000) form. Correct form IDs are added.

5	The following rules apply to mentions of screens in the Acumatica mobile app: The word “screen” is used (not “form”). Screen names are correct, including whether the name ends with an “s”: the Customers screen, the Sales Orders screen. No ID is added to the screen name.

6	Correct terms and correct names of UI elements are used.

7	Lowercase is used for phrases describing records created on forms or screens, such as generic inquiry, sales order, invoice, non-stock item, stock item, kit, or case. (Form and screen names are in title case; record names are lowercase.)

8	Correct prepositions, such as the following, are used: in the dialog box, in the Summary area, in the mobile app, in the Self-Service Portal on the form, on the Details tab, on the More menu

9	If an error message in the PD has any IDs of records, such as customer accounts or reference numbers of documents, they are replaced with placeholders within the < and > characters. Angle brackets <> are NOT used. Example: the <Purchase Order ID> blanket purchase order.

10	Correct phrases are used to introduce error messages, such as the following: … the following error message was shown: … the following error message was displayed: … the system showed the following error message: … the system displayed the following error message:

11	Error messages are not placed in the middle of the sentence (which makes the sentence long and difficult to read).

The correct version or build mention, such as the following, is used, as shown in the following examples:

After an upgrade to Acumatica ERP 2023 R1 or later major versions, …
After an upgrade to Acumatica ERP 2023 R2 Update 5 or later, …
After an update or upgrade to Acumatica ERP 2023 R2, …
After an upgrade to Acumatica ERP build 21.209.0034, …
After an upgrade to Acumatica ERP 2023 R1 GA through Update 4, …

The resulting text is coherent, and the connections between the sentences are clear.

Click to view some examples

Correct Example

Incorrect Example

The text is unified, and the sentences are logically connected.

The text does not flow smoothly, and the feature preconditions are not written in a way that clarifies or connects the conditions. Also, some unnecessary part names of the PD remain in the text.

If a user opened a service order on the Service Orders (FS300100) form and the order had many billed appointments, it took several minutes to load the form. The issue occurred if the following settings were specified in the billing cycle of the customer on the Billing Cycles (FS206000) form:

The Appointments option button was selected under Run Billing For.
The Service Orders option button was selected under Group Billing Documents By.

Workaround: To resolve this issue, you need to publish a customization project. Please contact your Acumatica support provider to receive the customization project and full assistance with its use.
Fix Description: The changes introduced in AC-267767 have been reverted. These changes allowed users to view the list of invoices created from an appointment or service order on the Billing Documents tab of the Service Orders (FS200100) or Appointments (FS300200) form, respectively, regardless of the customer’s billing cycle.

Bug Preconditions (if applicable):

On the Billing Cycles (FS206000) form
Run Billing For = Appointments
Group Billing Documents By = Service Orders

Bug Description or Change Description (required): If a user opened a service order on the Service Orders (FS300100), it took several minutes to load the form.
Affected User Scenarios (if applicable): A user opened a service order on the Service Orders (FS300100) form and the order had many billed appointments.
Workaround (if applicable): To resolve this issue, you need to publish a customization project. Please contact your Acumatica support provider to receive the customization project and full assistance with its use.
Fix Description (if applicable): The changes introduced in AC-267767 have been reverted. These changes allowed users to view the list of invoices created from an appointment or service order on the Billing Documents tab of the Service Orders (FS200100) or Appointments (FS300200) form, respectively, regardless of the customer’s billing cycle.

Checklist: Labels for a Late PD

1	If the PD is not included in the release notes because it was prepared too late and release notes need to be republished, the PDLate and PDRepublish labels have been added to the Jira issue. For details, see the process description in Confluence: Release Notes Preparation Process.

Examples of PDs

PD for a Bug

A bug is an issue in the system related to incorrect functionality or a UI defect.

Examples

AC-233749: If a user processed a customer statement on the Print Statements (AR503500) form, the system generated an email from an incorrect default email account.

AC-284193: On the Bank Deposits (CA305000) form, if the same cash account was selected in the Cash Account and Cash Drop Account boxes, a user could not void the deposit.

Fix Description: If the same cash account is selected in the Cash Account and Cash Drop Account boxes for a bank deposit and the deposit is voided, the value in the Cash Drop Account box will be cleared.

PD for a Product Change

A product change is a new change or enhancement in the system.

Examples

AC-280495: On the Inventory Summary (IN401000) form, the following check boxes have been renamed:

Expand by Lot/Serial Number to Expand by Lot/Serial Numbers
Expand by Cost Layer Type to Expand by Cost Layer Types

AC-250756: On the Project Tasks (PM302000) form, the Manage User-Defined Fields command is now available on the Customization menu. A user can now save a project task with user-defined fields and copy and paste a user-defined field to a new project task.

Optional: HTML Tags in PDs

After the PM or BA has added the PDValid label to the Jira issue, the Doc Watcher adds tags to public descriptions. These tags make the final text consistent with documentation: Form names, names of UI elements, names of system objects, error messages, and links appear in different fonts to make this content easy to distinguish at a glance. However, if you want to add tags, you can do this yourself; this is not forbidden.

The following HTML tags should be used in public descriptions:

for UI elements (such as buttons and tab names, names of boxes).
for form names and form IDs, error messages, names of features, names of options selected from a list, names of files and folders, and file paths.
<tt></tt> for various parameters (such as property and method names), names of database tables and other database components, names of functions, and text that the user types (for example, in a workaround)
For breaking changes, the API names should look as follows: <tt>CA0001DB.Result.FinYTDBalance</tt>. You need not add the form name.
for a line break. For example, if the PD has the Fix Description or the Workaround part (or both), it should start from a new line. After select Enter to start the new line.
<ol><li></li></ol> for an ordered list.
<ul><li></li></ul> for an unordered list.

Optional: The Given-When-Then (GWT) formula

The parts of a PD correspond to the Given-When-Then (GWT) formula that can be used in specifications and test designs:

Given (the known state of the system needed to achieve a negative scenario) = Bug Preconditions
When (a sequence of user actions triggering the negative scenario) = Affected User Scenarios
Then (the resulting negative scenario, such as an error or functional inconsistency, data corruption, or a performance issue) = Bug Description

You can use the GWT formula when you are writing a PD.
Given
The Bug Preconditions (if the bug has this part) have the following information:

Conditions under which the issue occurred
The enabled system features specific to the issue
Any system settings specific to the issue

When
The Affected User Scenarios (if the bug has this part) have the steps and actions that the user performed to encounter the bug.

Then
The Bug Description answers the applicable questions:

What issue has occurred in the system? On which form or forms did it occur?
What issue has occurred in the mobile app? On which screen or screens of the mobile app did it occur?
Which functionality worked incorrectly?
Which system objects have been affected?
What error message was shown to the user?