Feedback and Human Corrections

The people who know your org best are your own teams. aprity lets them correct the documentation where they read it, and shows what the next analysis did with each correction.

There are three parts:

• Feedback -- written on a rule, a page or a user story, directly in the portal.
• Human corrections -- the page that lists every correction and its outcome.
• Vocabulary -- the terms and acronyms your teams use, sent to the analysis.

Feedback is included on every plan.

Giving feedback

In the portal, look for the feedback control:

• next to a business rule in an object's rule register (Give feedback on rule ...),
• on a page (Feedback on the page),
• on a user story of the Migration backlog (Give feedback on this user story).

Then:

1. Pick the Feedback type:

   Type	Use it when
   Correction	The text is factually wrong.
   Removal	The text should not be there.
   Addition	Something is missing.
   Clarification	The text is correct but hard to understand.
   Obsolete	The item is no longer used by the business.

2. Write a Comment (required). Describe what should change and cite the source if you can.

3. Optionally, Suggest corrected text.

4. Click Send.

Each item keeps one active contribution. If someone already contributed on the same item, the portal warns you: yours will replace it, and the earlier one stays available in the history. There is also a limit on active contributions per item; archive an earlier one to add a new one.

What happens to your feedback

A small marker next to the item shows where your contribution stands:

Marker	Meaning
awaiting the next scan	Recorded; it will be sent to the next analysis.
sent to the analysis, verdict undetermined	The analysis received it; its effect could not be established.
taken up by the analysis	The next analysis took it into account.
sent, not taken up by the analysis	The analysis received it but did not apply it.
applied	The correction is reflected in the documentation.
archived	The contribution was archived and is no longer active.

Corrections on business rules are sent to the next analysis. On other kinds of items, some feedback is recorded for review by aprity and is not re-applied automatically on the next scan; the form tells you when that is the case.

Feedback is taken into account from the next scan. A contribution written after a scan has started is sent to the following one.

The Human corrections page

Open Human corrections in the Quality group of the rail. It lists the corrections written on this documentation: what each person flagged, and what the latest analysis did with it.

• Browse the list by Origin (people, or aprity's own automated analysis), State (written, submitted for analysis, applied, not applied, undetermined), Kind, Target type or Status (active, archived, superseded), or search by comment, target or code.
• Open an item to see its details: author, type, date, source scan, full comment, proposed text, history, and a link to the page it concerns.
• The Unlinked filter shows feedback whose target can no longer be found -- because the rule disappeared from the org, or because several rules could match.

Everyone with portal access can read this page. Users with the aprity Admin permission set also get a Moderation mode, where they can Archive a contribution or Mark as superseded.

Your vocabulary

Every organization has acronyms and internal terms that an outsider -- or an AI model -- would not understand. Open Vocabulary from the user menu to list them, with a definition and an optional category.

• The terms are sent to the analysis, so the documentation uses your words instead of guessing their meaning.
• One definition here replaces the same correction written on dozens of rules.
• Until you save your own vocabulary, a built-in default applies. Saving replaces it entirely.
• The number of terms is capped; the page shows how many you have used.
• Saving a changed vocabulary makes the next scan re-analyze the org's components so that the new wording reaches the documentation. Saving without changes costs nothing.

Tips

• Be specific and cite the source (a field, a rule, a record type). Precise feedback is more likely to be taken up.
• Use the vocabulary for recurring terms, and feedback for one-off errors.
• After a scan, open Human corrections to check which contributions were taken up and which were not.