No matter how well you know your technical product, you’ll never know it through the eyes of your users. In fact, the better you know your product, the harder it gets. You need external input from developers, architects, or other technical roles that implement your product. In this post, we’ll cover four ways you can get it.
The methods shared here are of increasing granularity and complexity:
- Provide a feedback widget
- Allow direct edit suggestions
- Provide live chat support
- Perform developer experience testing
As you may be able to gather from these feedback techniques, they’re not mutually exclusive. You could do all of these, but we’d recommend against trying all at once!
Each approach gets its own section below, with some examples of successful technical products whose path you can follow.
Ask For Feedback and Read What They Say
The simplest way to hear from developers is to ask them. Since you can’t always talk to developers in real time, you can solicit their response right in the documentation. In addition to a help or support section, include a feedback widget embedded in each page.
You’ll want to pass along the context of the feedback, most importantly the URL where the developer provided their response. A tool like Saberfeedback can include different types of widgets and important contextual information. You can even include this within your dashboard and optionally send user-specific data.
Algolia’s documentation includes the very simple approach shown above. Each page includes the question, “Did you find this page helpful?” with a green thumbs up and red thumbs down. Only when you interact with it does the full form pop out.
Ideally, Algolia tracks the up/down votes, making the additional information optional. That way, they receive feedback with the bare minimum developer hurdle. That said, the text field of additional information can be gold for informing your roadmap, building new content, or simply fixing whatever issue the developers have noticed.
It may seem obvious, but you only learn from developers if you actually read that feedback.
There was a time when I worked at Zapier when we took our eyes off this important developer communication. We had feedback widgets installed on every page but didn’t regularly review them. Honestly, I didn’t even know where the feedback went!
One of the platform engineers discovered where developer responses were stored. With a quick use of our own product, we Zapped new feedback into a Slack channel for the whole team to see.
Make sure you not only collect feedback but also review it frequently. If you’re already doing this, you may be ready for the next step: soliciting documentation edits from developers.
Accept Docs Edits Directly from Developers
September 12, 2013, was a typical day on the Web. For the SendGrid team, where I worked at the time, it marked an important step in developer outreach: the day we open-sourced the SendGrid documentation. Though I’d spent years prior at ProgrammableWeb seeing a lot of developer engagement practices, I hadn’t seen this before.
It was the project of Brandon West, SendGrid’s first developer evangelist. And it’s now a fairly accepted and great way to engage a technical audience.
A typical modern example looks like this page from Linode:
In Linode’s case, a small GitHub icon opens the option to edit the page’s contents. In other cases, it may be in a sidebar or at the bottom of the page. Follow the link and you’re taken to some form of content management system to make a suggested edit.
What happens next depends on your setup, but it will likely need to be reviewed before it is published. In the case of GitHub edits, the most common that we’ve seen, developers will create a Pull Request that needs to be merged into production.
When we looked at documentation of 30 top developer companies, we discovered nearly half of them accept edits directly from developers. While most push the revision system to GitHub, some use built-in content management, which does not require the developer workflow. That’s a trade-off and will depend on the technical comfort of your audience—but if they’re developers, chances are they spend much of their days in source control.
Unsurprisingly, GitLab uses its own service for developer edit suggestions. Also notable are the many different options they offer developers to provide feedback or get help. The menu of selections is hidden under a simple drop-down on every page of the company’s documentation.
Clear support options, as we see from GitLab, are among the 13 criteria of a great developer experience. One prevalent approach is live chat, but there are only a few circumstances where we’d strongly recommend you seek feedback this way.
Only Use Live Chat if You Can Support It
In the age of chatbots, it’s common to see a little icon in the bottom right of a page. Let’s be honest—how often is what’s behind that icon actually helpful?
Yet, I’ve seen developer-focused companies rush to all means of live chat support.
If it’s not an on-site option, it’s a Discord channel (or before that, Slack; and before that, HipChat; and before that, IRC).
Truly live chat can be great for devs and the company. You get feedback directly, with an opportunity to ask follow-up questions. Assuming there’s a solution to the issue, you may even solve their problem in the moment. What a great developer experience!
Yet live chat is expensive to staff and hard to do well. Chances are the people who have the answers also have other duties. If you merely have staff search for keywords and respond with links to documentation, you can probably get similar results with a bot.
Another approach will be to use “the community” to answer questions. That may work if you have a lot of passionate community members. But you can’t count on it as an official channel unless you include your own team. In that case, declare the hours publicly, and make sure a team member is available.
More important than live chat is a clear support path for developers. Encourage questions and feedback through the method where you know you can provide timely responses. And always, always, create a support feedback loop, so you can get the voice of developers to product, documentation, or other teams that need to hear this feedback from your technical users.
Watch Real Developers Try to Use Your Docs
While the previous methods were reactive, this final way to get documentation feedback from developers requires you to be proactive—and to bring your thickest skin. You don’t need a formal usability test to gain insights from developers, nor do you need a statistically valid sample. In fact, you’ll probably learn a lot by looking over the shoulder of a single developer.
You can watch developers in person, on a video call with screen sharing, or even asynchronously with session replay software. Get ready to witness confusion, frustration, and a few dead ends. For this reason, it’s better to be live with developers, so you can get their commentary and understand their motivations.
Here are a few tips to make the most of your developer research:
- Find the right developers
- Provide a realistic scenario
- Shut your mouth and watch
You could grab someone from your engineering team. You may learn something from their experience, but they also have inside knowledge that may influence their actions. Ideally, you find developers who frequently solve the sorts of problems that your product addresses. Then, crucially, ask them to perform specific actions that will move them forward with your product.
The hardest part is watching as they get lost and search for answers. Don’t bail them out of this struggle too early or you’ll miss out on important insights.
This little Slack screenshot shows the backchannel for one of those moments at Zapier:
An external developer attempted to install the platform CLI on their Windows machine, but the team had never tested it on Windows. This simple act of watching a developer use their technical product found an edge case that would have been harder—and more embarrassing—to locate without the screen-sharing session. Importantly, the team quickly made a fix to support Windows after that call.
You’ll also want to incorporate what you learn from watching developers. Similar to actually reading the feedback, taking action—through new documentation content, informative blog posts, and product changes—is an important step with all developer feedback.
Decide Where to Focus Your Efforts First
A great developer experience includes feedback from the people who implement or integrate your product. Based on that feedback, you’ll improve many, many areas of your documentation, dashboard, and content.
You can get a high-level idea of where you need to focus by answering a few questions in our free DX quiz.
You’ll be asked 13 questions about your website and developer documentation, which you can use to identify areas where you most need developer feedback.