Mediocre docs are sabotaging your growth
Fix your docs (and your funnel) with insights from Dave Nunez, a leading expert in developer education
If there’s one person who has set the gold standard for documentation it is Dave Nunez. If you’ve ever gone to the Stripe docs to get inspiration, then you were looking up what Dave and his team meticulously crafted. Dave led the documentation team at Stripe for five years. Before that he oversaw all of Uber’s technical content and information systems. Today he’s advising and consulting through Abstract Group.
If your docs are just average or in bad shape this interview has everything you need to start making real, tangible improvements. We’ll cover:
Personality traits that make for a great technical writer
Metrics for measuring success in documentation (it’s not pageviews)
How marketing can be a strong partner to a docs team
When to hire writers and what to look for
How Dave approaches fixing “broken” or gnarly documentation
Stories from Dave’s time at Stripe that will help you understand his approach to all things documentation and user experience (user research played a huge role)
And I’ll just leave this screenshot here:
How did you get into technical writing and know that documentation writing, strategy and leadership was for you? What personality traits make you especially good at it?
I graduated with an English degree and love writing. After trying every business writing job I got a call from a friend whose startup was looking for a technical writer, and pretty quickly I fell in love with technology and startup culture where anything goes to get the job done.
I came to believe that documentation was a completely underutilized vessel for business and customer success. It was as if everyone in the industry expected customers to have a painful experience in the docs. So I decided to act like a product manager, but for docs. Product managers work with engineers, they take user feedback, they evaluate the end-to-end user experience of their product. Once I started getting traction I was hooked and wanted to see how far I could take it.
Personality traits for success in this role:
You have to love to write. You’re going to be dealing with text all day, every day.
You have to love complex subject matter and learning. In this role you have to be able to learn a new technology well enough to teach very smart people how to use it. That’s ridiculous! The unlock is to get very good at learning quickly, to stay close to engineering and immersed in the product.
And finally, I’m super competitive, so I got into this race to try and build the best thing possible in a very niche field. Nobody knew they were competing with me, but I was out to win.
As an interesting wrinkle I (Ceci) will add:
Dave was not a developer when he got into technical writing! He took night classes, read tons of books, and did Codeacademy. In his self-led developer education he learned that one of the key traits of a great docs writer is that you have to be able to learn new technical concepts quickly, being nimble and open to change instead of being a technical specialist because this will allow you to grow, change jobs, and take on more products over time.
As a marketer I see (external facing) docs as an essential part of the developer funnel - how often do you partner with marketing in your work? What marks a good marketing partner for you vs a weak one?
I love partnering with marketing. We share a lot in common:
We’re creating content and have to educate developers, who probably don’t really want to deal with consuming marketing content or docs.
Within an organization we face high expectations, short timelines, and a lot of collaborators who don’t really understand what we do.
Let’s start with what makes a weak marketer, because unfortunately they do exist. I think that ultimately a weak marketer stays in their lane and is afraid to jump into the fray with R&D. You cannot do a good job if you’re not willing to attend meetings with engineers and PMs. Your credibility as a marketer goes way up when you actually test products and give feedback – the rest of the team wants you to have an informed opinion!
The strongest marketers I’ve worked with are super secure in the value they bring. They have no shame in convincing the team that it’s extremely important to get the naming, or one-line description, or GTM strategy of the product right. The most successful marketers at Stripe were also the ones who pushed back when necessary. Not only did they do great work, but they earned the respect of leadership by fighting for the best ideas.
What do you wish marketing would do to support docs strategy? Are there any stories of working with marketing where your efforts were improved by strong marketing partnership?
At Stripe we had a sprint called “integration experience” that ran for 12-15 months that all started with a bad user tweet, as many people’s nightmares at founder-led startups begin. Ultimately we were trying to fix the integration experience, which had gotten messy because of regulatory requirements outside of our control like GDPR and Strong Customer Authentication.
After a good 3-6 months of trying to solve this problem someone else tweeted about their confusion and a ton of people piled on in agreement, which ended up on Hacker News. The external validation flipped a switch internally and we designed a sprint to make the necessary hard decisions to make Stripe simple again, instead of passing our internal complexity onto our users.
We pulled in data scientists, product marketers, user researchers, designers, and engineers and we ended up creating a really good product experience and great documentation. The product marketers that come to mind were there in the trenches with us. They weren’t trying to force anything or lead the charge, they were there when they were needed and knew when they didn’t need to be part of a decision. They had all of the contacts and relationships ready to help us and they stayed very even keeled. When we worked on the docs and felt stuck with naming, or messaging, or positioning they had the context and could give us the quick answer and unblock the team. That was priceless.
This is a basic question but I’d love your quick framework for what makes docs good or bad?
Ultimately good docs are written for people.
Patrick and John Collison talked about the experience of Stripe’s docs being akin to sitting with a friend over coffee, who's telling you how to set up Stripe. A friend will tell you what to use, what to avoid, and maybe pull up a useful YouTube link.
When we wrote documentation we’d picture a human being who has maybe 30-60 minutes of uninterrupted time. Good docs are short and easy to scan. They have good UX, strong search, and the layout has some white space.
Bad docs are the opposite. A lot of the time they are written for machines or for people that don’t exist. You can always tell when docs are written to make automated translation easy because the language is stilted and robotic, and thus cheaper to translate. Other bad docs are just walls of text and make the unrealistic assumption that developers want to read that much.
How do you measure success in the world of documentation?
Time to X.
The best measure is the time it takes to accomplish whatever task you want the developer to achieve. At Stripe we looked at the activity that got people over the initial hump for onboarding: running a test charge. We obsessed over that onboarding experience, and smoothed over every tiny paper cut to get there. As a result we shortened the experience to 4x less time on average.
Support contact rate.
Documentation managers obsess over how many support tickets they’re deflecting - because that justifies the budget for their team. When I brought that metric to Stripe I was very proud that we saw support contact rates go down to something like under a percent, when it had previously been quite high!
To my surprise, John Collison was like, yeah that’s nice but we shouldn’t focus on the dollars saved – this is really good because of the user experience. Users don’t want to have to contact support, so let’s make documentation so good that they don’t have to.
Who cares about page views.
You can look at Google analytics, page views, bounce rates, and maybe CSAT but I find these metrics to be much less meaningful on their own.
What do you find yourself repeating to your clients about docs? What’s the fastest change companies can make to see significant gains?
Obsess over the getting started experience. Many clients who want to have great docs think they have to do everything all at once. Tackling everything usually leads to burn out. Alternatively they get paralyzed by all the work that needs to be done and can’t take any steps forward.
Your users are never going to pay you if they can’t even get started, so fix that first. Once you’ve done that then you can start worrying about the rest; information architecture, design, search, all of that stuff. To fix getting started:
Build a friction log. Get everyone in your company to go through your getting started experience. Uncover all of the gaps and toil to go live.
Do user research; find the biggest activation hurdles. Sometimes it’s a confusing automated email with a broken link. Sometimes it’s a missing CTA from your marketing page. Most of the time it’s confusing documentation and a product that is out of touch with user needs.
Little paper cuts add up. It doesn’t matter if you’re enterprise or PLG, first impressions matter greatly. The trust you build with the user through a great onboarding experience is priceless. Stripe’s developer experience was far from perfect, but we were always iterating and improving to the point where devs gave us the benefit of the doubt, and they would aim to unblock themselves and/or give us feedback because they knew we’d take it seriously.
Can you tell me a story about an improvement or change that you made to the Stripe docs that made a surprisingly big impact?
There’s one study we ran which ended up delivering a completely different result from what we expected.
At Stripe we did a ton of user research, both formally with user researchers and informally for ourselves. During that integration experience sprint we were trying to understand why our users were finding Stripe so complicated. We went into conversations thinking that we knew what the problems were…
But, 10 minutes into a user interview the user would have 10 tabs open. And then, 20 minutes in they’d have 15 tabs open and they were flustered. We forgot to consider that developers deal with a ton of context switching – waiting for something to compile, a PR to be reviewed, getting Slack messages, checking email, running to meetings – so if you create this extremely fragmented experience with 15 tabs then of course they’re going to have a negative feeling.
It turns out we had used tons of inline links in our docs because that was the SEO playbook, but, we found out, developers would click on every link assuming that they all needed to be read and soon they were buried in tabs.
So, we threw out the SEO playbook and stopped linking inline unless it was absolutely necessary. After that the docs team built this really cool hover capability and the writers wrote an extensive glossary, so you could hover over a term and the definition would pop up. This kept users on a single page and with many less tabs.
How do you think about hiring writers? And how do you know when to hire a full time person to own documentation?
I look at the team’s needs. At some places you need senior hires because they’ve seen all of the problems you’ll face. They know how to handle messy stuff like migrations or big information architecture overhauls. Junior people, on the other hand, can be great because they come in with fresh eyes and are willing to do the dirty work that senior writers are sick of.
If you have a developer-focused product you should be thinking about hiring a documentation person from day 1. You’ll be writing a lot of content yourself in the early days, and you should fantasize about having a full-time writer: who are they? What skills do they have? Then, in 2 years when you’re succeeding and ready to hire your first technical writer it won't take you 3-6 months. You’ll already know who the right person is and can go find them in a 2-4 week search.
To really quantify “when,” consider when your engineers are collectively spending more time on documentation than a full-time hire could take off of their plates. A technical writer at this point will save you money and improve the quality of your docs.
⚡️ Lightning round
Whose docs do you love these days?
Sadly still Stripe. When I need to see how to do a thing I look to Stripe - I know how much user research goes into their decisions, and I also have a good idea of how they think, so I can evaluate their design choices.
What developer brand do you think is fire right now?
Brand wise a couple have a halo that is hard to acquire – and once you have it there is so much goodwill and trust built up with developers that it creates a moat.
Linear - their product is a huge win for developers who never wanted to see a ticket again and somehow, with Linear, they’re glad it exists!
Graphite.dev - they’re actually a former client, but I always hear devs talk about how awesome they are. Being on the inside I got to see this because the team lives in their tool and they are constantly pulling feedback from users and making tiny improvements every day or two - and it adds up!
One pro and one con of consulting?
Pro: working with a ton of startups. They're willing to take big risks that big companies aren’t.
Con: you don’t get to have those hallway conversations that turn into prototypes and eventually become something novel in the product because you’re not with the team for a long time, running in the same direction and dreaming big.
Unpopular opinion when it comes to technical writing or documentation?
I think that most documentation doesn’t need to exist. People think that exhaustiveness is the goal and you end up with these dev products with endless pages of content, answering every possible question, but when your product is changing rapidly it’s not feasible to maintain this kind of documentation. You should focus on the work that 60-80% of your core users need and be conscious about the edge stuff to know when it needs to be developed. Don’t be afraid to delete or trim pages! That mindset forces you to be focused on your product itself, as well, because if you’re trying to do too many things for too many people it’s going to show up in the documentation and will convey complexity and lack of focus to your users.
Huge thanks to Dave for all of his insights! You can follow Dave on LinkedIn and check out his consulting work at Abstract Group.