Documentation Feedback Form
The Documentation Feedback Form helps product and developer experience teams continuously improve their documentation. Whether it's API docs, user guides, or knowledge base articles, this form collects structured feedback on helpfulness, accuracy, clarity, and completeness. With thumbs rating for quick assessment and optional detailed feedback for improvements, you'll understand exactly what's working and what needs attention. The conditional flow ensures you capture specific issues when users indicate problems.
Try the Form
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
export function documentationFeedbackForm(form: FormTs) {
// Documentation Feedback Form
// Demonstrates: ThumbRating, StarRating, EmojiRating, RatingScale,
// CheckboxList, SuggestionChips, Textarea, multi-page wizard
// ============================================
// PAGES STRUCTURE
// ============================================
const pages = form.addPages('feedbackPages', {
heightMode: 'current-page'
});
// ============================================
// PAGE 1: Quick Feedback
// ============================================
const page1 = pages.addPage('quickFeedback');
page1.addRow(row => {
row.addTextPanel('header', {
label: 'Documentation Feedback',
computedValue: () => 'Help us improve this documentation. Your feedback matters.',
customStyles: {
backgroundColor: '#3b82f6',
color: 'white',
padding: '24px',
borderRadius: '12px',
textAlign: 'center',
fontSize: '15px'
}
});
});
const quickSection = page1.addSubform('quick', {
title: 'Was this page helpful?'
});
quickSection.addRow(row => {
row.addThumbRating('wasHelpful', {
label: '',
showLabels: true,
upLabel: 'Yes, helpful',
downLabel: 'No, needs work',
alignment: 'center',
size: 'lg'
});
});
// Conditional emoji rating based on thumb
quickSection.addSpacer({
height: '16px',
isVisible: () => quickSection.thumbRating('wasHelpful')?.value() !== null
});
quickSection.addRow(row => {
row.addEmojiRating('experience', {
label: () => {
const helpful = quickSection.thumbRating('wasHelpful')?.value();
if (helpful === 'up') return 'How was your documentation experience?';
return 'How frustrated were you?';
},
preset: () => {
const helpful = quickSection.thumbRating('wasHelpful')?.value();
return helpful === 'up' ? 'satisfaction' : 'effort';
},
size: 'lg',
showLabels: true,
alignment: 'center',
isVisible: () => quickSection.thumbRating('wasHelpful')?.value() !== null
});
});
// Navigation for positive feedback - go to page 2
const positiveNav = page1.addSubform('positiveNav', {
isVisible: () => quickSection.thumbRating('wasHelpful')?.value() === 'up'
});
positiveNav.addSpacer({ height: '16px' });
positiveNav.addRow(row => {
row.addButton('toPositiveDetails', {
label: 'Tell us more (optional) →',
onClick: () => pages.goToPage('positiveDetails')
});
});
// Navigation for negative feedback - go to page 3
const negativeNav = page1.addSubform('negativeNav', {
isVisible: () => quickSection.thumbRating('wasHelpful')?.value() === 'down'
});
negativeNav.addSpacer({ height: '16px' });
negativeNav.addRow(row => {
row.addButton('toNegativeDetails', {
label: 'Help us improve →',
onClick: () => pages.goToPage('negativeDetails')
});
});
// ============================================
// PAGE 2: Positive Feedback Details
// ============================================
const page2 = pages.addPage('positiveDetails');
page2.addRow(row => {
row.addTextPanel('positiveHeader', {
label: 'Great to hear!',
computedValue: () => 'Tell us what worked well so we can do more of it.',
customStyles: {
backgroundColor: '#10b981',
color: 'white',
padding: '20px',
borderRadius: '12px',
textAlign: 'center'
}
});
});
const positiveSection = page2.addSubform('positive', {
title: 'What did you like about this documentation?'
});
positiveSection.addRow(row => {
row.addSuggestionChips('whatLiked', {
label: 'Select all that apply',
suggestions: [
{ id: 'clear', name: 'Clear and easy to understand' },
{ id: 'complete', name: 'Complete information' },
{ id: 'examples', name: 'Good code examples' },
{ id: 'organized', name: 'Well organized' },
{ id: 'accurate', name: 'Accurate and up-to-date' },
{ id: 'quick', name: 'Found answer quickly' }
],
alignment: 'center'
});
});
positiveSection.addSpacer({ height: '16px' });
positiveSection.addRow(row => {
row.addStarRating('docQuality', {
label: 'Overall documentation quality',
maxStars: 5,
size: 'lg',
alignment: 'center',
showConfettiOnMax: true,
filledColor: '#10b981'
});
});
const positiveFeedback = page2.addSubform('positiveFeedback', {
title: 'Additional Feedback'
});
positiveFeedback.addRow(row => {
row.addTextarea('positiveComments', {
label: 'Anything else you\'d like to share?',
placeholder: 'Your suggestions for improvement...',
rows: 3,
autoExpand: true
});
});
const positiveNavBack = page2.addSubform('positiveNavBack', {});
positiveNavBack.addRow(row => {
row.addButton('backFromPositive', {
label: '← Back',
onClick: () => pages.goToPage('quickFeedback')
});
});
// ============================================
// PAGE 3: Negative Feedback Details
// ============================================
const page3 = pages.addPage('negativeDetails');
page3.addRow(row => {
row.addTextPanel('negativeHeader', {
label: 'We want to do better',
computedValue: () => 'Help us understand what went wrong so we can fix it.',
customStyles: {
backgroundColor: '#f59e0b',
color: 'white',
padding: '20px',
borderRadius: '12px',
textAlign: 'center'
}
});
});
const issueSection = page3.addSubform('issue', {
title: 'What was the main issue?'
});
issueSection.addRow(row => {
row.addCheckboxList('issueTypes', {
label: 'Select all issues that apply',
options: [
{ id: 'unclear', name: 'Content was unclear or confusing' },
{ id: 'incomplete', name: 'Information was incomplete or missing' },
{ id: 'inaccurate', name: 'Information was inaccurate or outdated' },
{ id: 'examples', name: 'Code examples didn\'t work' },
{ id: 'hard-find', name: 'Hard to find what I needed' },
{ id: 'too-technical', name: 'Too technical / assumed too much' },
{ id: 'too-basic', name: 'Too basic / not enough detail' }
],
orientation: 'vertical',
isRequired: true
});
});
// Conditional follow-ups based on issues selected
const missingSection = page3.addSubform('missing', {
title: 'What information was missing?',
isVisible: () => {
const issues = issueSection.checkboxList('issueTypes')?.value() || [];
return issues.includes('incomplete');
},
customStyles: { backgroundColor: '#fffbeb', padding: '16px', borderRadius: '8px' }
});
missingSection.addRow(row => {
row.addTextarea('missingInfo', {
label: 'Please describe what information you were looking for',
placeholder: 'I was trying to find information about...',
rows: 3,
isRequired: () => {
const issues = issueSection.checkboxList('issueTypes')?.value() || [];
return issues.includes('incomplete');
}
});
});
const inaccurateSection = page3.addSubform('inaccurate', {
title: 'What was inaccurate?',
isVisible: () => {
const issues = issueSection.checkboxList('issueTypes')?.value() || [];
return issues.includes('inaccurate');
},
customStyles: { backgroundColor: '#fef2f2', padding: '16px', borderRadius: '8px' }
});
inaccurateSection.addRow(row => {
row.addTextarea('inaccurateInfo', {
label: 'Please describe what was incorrect',
placeholder: 'The documentation says X but actually...',
rows: 3,
isRequired: () => {
const issues = issueSection.checkboxList('issueTypes')?.value() || [];
return issues.includes('inaccurate');
}
});
});
// Rating and comments
const ratingSection = page3.addSubform('rating', {
title: 'Additional Details'
});
ratingSection.addRow(row => {
row.addRatingScale('clarityRating', {
label: 'How clear was the writing?',
preset: 'likert-5',
lowLabel: 'Very confusing',
highLabel: 'Very clear',
alignment: 'center',
size: 'md'
}, '1fr');
row.addRatingScale('completenessRating', {
label: 'How complete was the information?',
preset: 'likert-5',
lowLabel: 'Missing a lot',
highLabel: 'Very complete',
alignment: 'center',
size: 'md'
}, '1fr');
});
ratingSection.addSpacer({ height: '16px' });
ratingSection.addRow(row => {
row.addTextarea('suggestionBox', {
label: 'How could we improve this documentation?',
placeholder: 'Your specific suggestions...',
rows: 4,
autoExpand: true
});
});
// Contact option
const contactSection = page3.addSubform('contact', {
title: 'Need help?'
});
contactSection.addRow(row => {
row.addCheckbox('wantsFollowUp', {
label: 'I would like someone to follow up with me about this documentation issue'
});
});
contactSection.addRow(row => {
row.addEmail('contactEmail', {
label: 'Your email address',
placeholder: 'email@example.com',
isRequired: () => contactSection.checkbox('wantsFollowUp')?.value() === true,
isVisible: () => contactSection.checkbox('wantsFollowUp')?.value() === true
});
});
const negativeNavBack = page3.addSubform('negativeNavBack', {});
negativeNavBack.addRow(row => {
row.addButton('backFromNegative', {
label: '← Back',
onClick: () => pages.goToPage('quickFeedback')
});
});
// ============================================
// FORM CONFIGURATION
// ============================================
form.configureSubmitButton({
label: () => {
const helpful = quickSection.thumbRating('wasHelpful')?.value();
const page = pages.currentPageIndex();
if (page === 0 && helpful === 'up') return 'Submit Quick Feedback';
if (page === 0 && helpful === 'down') return 'Submit Quick Feedback';
if (page === 1) return 'Submit Positive Feedback';
if (page === 2) return 'Submit Detailed Feedback';
return 'Submit Feedback';
},
isVisible: () => quickSection.thumbRating('wasHelpful')?.value() !== null
});
form.configureCompletionScreen({
type: 'text',
title: () => {
const helpful = quickSection.thumbRating('wasHelpful')?.value();
if (helpful === 'up') return 'Thank you for the positive feedback!';
return 'Thank you for helping us improve!';
},
message: () => {
const helpful = quickSection.thumbRating('wasHelpful')?.value();
if (helpful === 'up') {
return 'Your feedback helps us know what\'s working well. We\'ll keep creating helpful documentation!';
}
return 'We take your feedback seriously and will review the issues you reported. Our technical writing team continuously works to improve our documentation.';
}
});
}
Frequently Asked Questions
Where should I place this feedback form?
Place it at the bottom of each documentation page, below the main content. A 'Was this helpful?' widget should be visible without scrolling on shorter pages. For longer articles, consider a sticky footer or sidebar placement for visibility.
What metrics should I track from documentation feedback?
Key metrics include: Helpfulness rate (% of positive ratings), Clarity score, Accuracy issues reported, Missing content requests, and Page-level performance comparison. Track trends over time to measure improvement efforts.
How do I prioritize documentation improvements?
Focus on pages with: High traffic + low helpfulness scores, Repeated 'information missing' feedback, Multiple accuracy complaints, Developer-facing docs with clarity issues. Weight by page importance and user segment.
Should documentation feedback be anonymous?
Yes, by default. Anonymous feedback gets more honest responses. However, offer optional contact for follow-up on complex issues. Some teams ask for email only when users report bugs or request callbacks.
What's a good helpfulness rate for documentation?
Aim for 80%+ positive ratings on core documentation. 90%+ indicates excellent docs. Below 70% requires immediate attention. Compare similar page types - tutorials might score differently than reference docs.
How should I handle negative documentation feedback?
Create a review workflow: Technical writers review negative feedback weekly, categorize issues (clarity, accuracy, missing info), prioritize by impact, make improvements, and track if ratings improve on updated pages.