Building a Feedback Loop
Your team knows things the metadata cannot say: why a rule exists, what a field really means, which process is obsolete. Reader feedback brings that knowledge into aprity. This page explains how feedback works and how to run it as a routine.
How feedback works
A reader opens a page or a rule in the web portal, gives feedback, chooses a type and writes a comment. The comment is required; a proposed corrected text is optional. The feedback is linked to that item and visible to the aprity Admin users of your organization.
What happens next depends on what the feedback targets:
- Rules, object overviews, processes and components (Apex classes, Lightning components, page layouts): the feedback is sent to the next analysis, which takes it into account when it writes the documentation again.
- Other targets (fields, integrations, user stories, pages...): the feedback is recorded and reviewed, but it is not re-applied automatically on the next analysis. The feedback form says so.
On a rule, a marker shows where the feedback stands: awaiting the next scan, sent to the analysis, taken up by the analysis, sent, not taken up by the analysis, or archived.
Feedback types
| Type | Use it when | Example |
|---|---|---|
| Correction | The text is wrong. | "This rule applies to Opportunities, not Accounts." |
| Removal | The text describes something that does not exist. | "This paragraph describes a check that the org does not have." |
| Addition | Something important is missing. | "This rule exists because of the partner contract; the discount cap is set by Finance." |
| Clarification | The text is right but hard to understand. | "Our teams call this 'onboarding', not 'activation'." |
| Obsolete | The item is outdated in your org. | "This process was replaced last year; the flow is only kept for history." |
Write feedback that works
- Be specific. "Wrong" is not enough. Say what is wrong and what is right: "This validation fires when the opportunity is closed, not when it is created. It blocks discounts above the limit set by Finance."
- Cite the source when you can: a field, a flow, a document, a person.
- One point per feedback. Separate items are easier to apply and to follow.
- Target the right item. Feedback on a rule is applied to that rule; feedback on a whole page is less precise.
There is a limit on the number of active contributions per item. If you reach it, archive one of your earlier contributions on that item.
Moderate feedback: Human corrections
Human corrections (in the Quality group of the portal menu) lists all feedback on the documentation, with what each person flagged and what the latest analysis did with it. aprity Admin users can moderate it:
- Archive feedback that is resolved, or that no longer applies because the org changed.
- Mark as superseded feedback replaced by a more recent one on the same item.
Only active feedback is sent to the next analysis. Archiving outdated feedback prevents old corrections from being applied to a changed org.
A weekly routine
- After each analysis, reviewers read the pages of their area and give feedback.
- Before the next analysis, the documentation lead opens Human corrections, checks new feedback, and archives what is outdated.
- After the next analysis, check the markers: taken up by the analysis means the correction was applied; not taken up means you should rephrase it or look at why.
Measure progress
- Less new feedback over time usually means the documentation fits your vocabulary and your context better.
- The same problem reported again means the feedback needs to be more specific, or targets the wrong item.
- Feedback that is never taken up is worth a closer look: the target may not be one that is re-applied automatically.