Five documentation feedback signals to track
Use page helpfulness, recurring feedback themes, CSAT, CES, and NPS when each signal supports a different documentation or customer decision.
Not every feedback metric answers the same question.
A documentation team trying to improve one page needs a different signal from a customer-success team measuring satisfaction with an interaction or the wider product relationship.
For most documentation work, start close to the page and task. Use broader metrics only when the decision you are making is broader too.
| Signal | Question it helps answer | Best used for |
|---|---|---|
| Page helpfulness | Was this page helpful? | Finding pages worth reviewing |
| Recurring feedback themes | What problem or task keeps appearing in comments? | Identifying repeated documentation issues |
| CSAT | How satisfied were you with this interaction? | Reviewing a defined support or documentation experience |
| CES | How easy was it to complete this task? | Finding friction in a specific workflow |
| NPS | How likely are you to recommend us? | Understanding the broader customer relationship |
1. Page helpfulness
A simple helpfulness question gives you a page-level signal.
For example:
Was this page helpful?
The result can help you identify pages worth inspecting, especially when you collect enough responses to see a pattern.
A helpfulness rating becomes more useful when readers can also explain what went wrong.
For example:
What were you trying to do?
A low rating tells you where to look. The comment can tell you what to investigate.
See how to use a helpfulness widget in docs for a simple page-level feedback workflow.
2. Recurring feedback themes
Comments can reveal problems that a numeric score cannot.
Look for repeated themes such as:
- a missing prerequisite
- an unclear API parameter
- an outdated example
- confusing terminology
- a broken link
- difficulty finding the next step
- repeated questions about the same task
The number of similar reports can help with prioritisation, but frequency is not the only factor.
One report about an incorrect production procedure may matter more than ten minor wording complaints.
Use recurring themes together with the importance of the task and the clarity of the evidence.
For a broader workflow, see how to collect and use documentation feedback.
3. CSAT
Customer Satisfaction Score, or CSAT, measures satisfaction with a defined experience.
For example:
How satisfied were you with the help you received?
CSAT can make sense after a support interaction, chatbot conversation, onboarding experience, or another identifiable moment.
It is less useful as a generic score attached to every documentation page because it does not automatically tell you what part of the page needs work.
Use CSAT when the thing you want to measure is the interaction itself.
4. CES
Customer Effort Score, or CES, asks how easy or difficult it was to complete a task.
For documentation teams, that can be useful for bounded workflows such as:
- creating an API key
- completing a quickstart
- configuring an integration
- migrating to a new API version
- troubleshooting a common error
For example:
How easy was it to create your first API key?
CES is useful when you care about the effort required to finish a specific task rather than satisfaction with an individual page.
If the score changes, investigate the full task path. Documentation may be part of the friction, but product behavior, permissions, provisioning, or other steps may matter too.
5. NPS
Net Promoter Score, or NPS, measures the broader customer relationship by asking how likely someone is to recommend the company or product.
That makes it useful for a different question from page feedback.
A low NPS score cannot tell a technical writer which API example needs rewriting. A page-level comment can.
Use NPS when you want to understand the wider customer relationship, not as a substitute for documentation-specific feedback.
For definitions of the three broader survey metrics, see NPS, CSAT, and CES.
Compare the same signal after a change
When you want to see whether a documentation change helped, keep the comparison as consistent as possible.
For a page-level change, record:
- the page
- the feedback question
- where the prompt appears
- the review period
- the number of responses
- recurring comments or themes
After the update, use the same prompt and placement and review the feedback again.
For example, if readers repeatedly reported that an OAuth scope was missing, check whether that theme continues after you add the missing explanation.
The useful outcome is not simply that a percentage moved. It is whether the specific reader problem you were trying to fix still appears.
Use the narrowest signal that answers the question
Do not start with NPS when the problem is one confusing documentation page.
Likewise, do not use one page rating to make a claim about the overall customer relationship.
A simple rule is:
- use page helpfulness and comments for page-level decisions
- use CES for task difficulty
- use CSAT for satisfaction with a defined interaction
- use NPS for the broader customer relationship
Choose the signal that matches the decision you need to make.
Frequently asked questions
Can documentation feedback replace NPS?
No. Page feedback helps with page-level documentation decisions, while NPS measures the broader customer relationship.
When is CSAT useful for documentation?
Use CSAT when you want to measure satisfaction with a defined interaction, such as a support or chatbot experience. Collect page or task context separately if you need to know what caused the response.
When should we use CES?
Use CES when you want to understand how difficult a specific task was, such as completing onboarding, configuring an integration, or making a first API request.
How much feedback is enough to act on?
There is no universal minimum. Act when the problem is clear enough to verify and important enough to fix. Repeated feedback can strengthen the case, but a single consequential issue may deserve immediate attention.
Which feedback signal should a documentation team start with?
For most documentation pages, start with a simple helpfulness question and an optional comment. Add CES, CSAT, or NPS only when the decision you are making requires a broader measure.
Start with the decision you need to make
Choose the feedback signal that matches the level of the problem.
If you need to improve a page, collect page-level feedback. If you need to understand a task, measure effort. If you need to understand a broader interaction or customer relationship, use CSAT or NPS.
Check PushFeedback plan limits when you are ready to add page-level feedback to your documentation.