As new features roll out and existing ones get updated, an enthusiastic crew of Netlify technical writers ensure that the Netlify docs site has thorough, up-to-date documentation. What happens after those swanky new docs get published, though? While it’s tempting to just rest on our laurels and call the job done, the Netlify Docs team instead monitors a number of channels for user feedback and makes iterative improvements to address clarity, content gaps, or corrections. This post summarizes our processes for making that magic happen.
Feedback form
At the bottom of every docs page, we provide a form for customers to share feedback with us. They can score the usefulness of the page with a thumbs up / thumbs down and write a comment to share their thoughts. When a reader submits feedback through this form, the submission triggers a serverless function that pipes information to an internal Slack channel as well as a spreadsheet.
But how much feedback do we get? As Bob Watson notes in his Docs by Design blog, docs feedback can be useful, even if it’s not statistically significant. For our site, we receive about 14 feedback items for every 10,000 page views, which is only 0.14%. About half of those include freeform comments. We find that the up/down votes are useful in aggregate, and we refer to those numbers in ad hoc ways for things like informing the prioritization of content overhaul projects. But the freeform comments are where we get the most actionable insights.
The Docs team has a feedback form rotation set up where each week one tech writer is responsible for reviewing all the new comments that come in and figuring out what, if anything, we can do about them to improve our docs. Sometimes we get nice compliments or wildly off-topic comments like someone professing a love of Grand Theft Auto or asking us for free diamonds. Some feedback is too vague to be actionable or covers an edge case that doesn’t warrant coverage in the docs site. A lot of comments, though, reveal actionable insights into pain points customers are having. Over the course of the last six months, the Docs team has published 40 updates based on this feedback. We’ve also used this information to file new issues, add insights to existing issues, and pass on feature requests to our colleagues in the Product team.
Support pairing
Another useful source of customer feedback comes through our Support and Community teammates. Each week, a different tech writer is on rotation to sync up with colleagues to take action on docs feedback that’s flagged in our Support Forums and through customer support tickets. We’ve made a dozen updates in the past six months from items that came through this channel. Because we build Netlify on Netlify, we make use of collaborative Deploy Previews to gather reviews from our support colleagues when we make these updates.
We’ve organized our Docs team to embed writers within groups that focus on certain areas of the Netlify platform. While this is useful for building up contextual knowledge and cross-functional team relationships, this setup can limit Docs team knowledge outside of a specific focus area. Engaging in feedback-related rotation work helps us maintain empathy for our users and understand the full capabilities of Netlify’s platform. It also helps us be good teammates to our Support organization. We work towards making our documentation clear, precise, and complete to deflect future support tickets and forum posts.
Internal stakeholders
Netlify has grown quite a bit as a company over the past few years. We are delighted to meet and collaborate with new colleagues from all over the world, but the true upside for the Docs team is that each new employee who uses our documentation to learn about our platform is a potential source of useful feedback. We encourage new folks and long-time employees to file issues or, even better, submit a pull request to our documentation repository. Because our team uses a docs-as-code workflow to manage our documentation site, contributing feels familiar for our engineers and other teammates.
Internal stakeholders from across the company also highlight content gaps or note what is tripping customers up, and our Developer Experience teammates pass along concerns from the various communities they are a part of. Our docs benefit from the insights of colleagues who interact with our user base every day.
Where to next
While we listen carefully to the feedback we receive, we recognize that there are more opportunities to help assess the success of our documentation in helping users achieve their jobs-to-be-done. We’d like to do more user research with our docs, and we are working to move the site feedback from a spreadsheet to a tool that will help us examine and track trends more efficiently. We are also exploring ways to make our Docs process more collaborative with the community. Wherever we go next, our goal is to help users find what they need, address their problems, and get on with their day feeling a little better.
