How Stripe Creates the Best Documentation in the Tech Industry

Ask any developer which company has the best documentation and you'll hear the same answer: Stripe.

While building Mintlify, I've grown to have a fixate on what makes documentation great and I've seen a lot of docs in my day, and it's clear to me that Stripe has set a high bar for developer tool documentation. Their docs are as usable as they are beautiful, and even more impressively, they're highly comprehensive. Each page feels thoughtful in both content and structure, giving the impression that it was made by people who consider documentation more than just a chore.

Stripe's documentation—and the impact it has had on the company's user experience, retention, and brand attributes to why the company's success.

But Stripe isn't alone in its goal of building the best docs. Many companies aspire to do the same but fail somewhere along the way. Why?

I went down this research rabbit hole, and here's how Stripe created the culture and habits that enabled their team of engineers to write beautiful docs.

Foster a strong writing culture

There are few companies that have embedded writing into their culture more than Stripe. The company has a literal press that publishes books, an engineering magazine, and one of the most widely read engineering blogs of any company in Silicon Valley.

As former Stripe employee Patrick McKenzie, put it: “Stripe is a celebration of the written word which happens to be incorporated in the state of Delaware.”

This culture starts at the top, according to Dave Nunez, Stripe's former Documentation Manager. “The first emails I saw from our CEO [Patrick Collison] literally had footnotes,” he told Slab in an interview. “He structured his emails to be like research papers and put the peripheral information at the bottom so as not to detract from the core information.”

For companies that want to build better docs, Nunez believes culture change is the biggest lever available. “I wouldn't recommend early-stage startups just go out and hire a full-time docs writer. I've learned that, especially in high-performance environments, changing the culture is the highest leverage investment you can make,” he told First Round Review.

It's worth noting that this takes work—and in some cases, behavior change—from leaders in a company. We've seen this reflected with the companies that use our docs— the POC in over 90% of our Slack Channels is either the CEO, CTO, or Head of Product.

“I've seen executives write emails all lowercase, loaded with abbreviations and typos, which gives the impression that the time they saved by writing a low-quality email is more valuable than the time it's going to take others to decipher it. Not only are people frustrated with the poor readability, but other employees will learn not to take writing seriously either,” Nunez told First Round Review.

My takeaway: When building a culture, actions speak louder than words. In order to get people to prioritize writing quality you have to demonstrate thoughtfulness and attention to detail every day. This is especially true for leaders who set the tone for everyone else.

Stripe created support systems to help developers write docs

Tactically, Stripe has also built systems and strategies that encourage developers to write docs.

When Nunez joined Stripe as its Head of Docs, he learned that many developers struggled with writer's block. They wanted to write documentation, but when it came time to sit down in front of the computer screen, they froze up.

He solved this problem by creating resources and guides for developers on how to write good docs. “We create docs that offer some of the basics, so engineers aren't forced to stare at a blank page — which can be terrifying,” Nunez told Slab.

Templates and resources didn't solve all of Stripe's problems, however.

Stripe is a globally distributed company with employees in dozens of countries around the world. As a result, many of the company's engineers aren't native-English speakers or writers. Soon after joining, Nunez learned that many ESL engineers struggled to write docs.

In order to support these employees, Stripe created classes on writing and documentation best practices; they offered these classes to new engineers during the onboarding process. They also created office hours where employees could seek advice from technical writers and documentation experts, according to Nunez.

My takeaway: Empowering each team member to write spreads ownership and responsibility. It also reinforces the belief that everyone should be writing high-quality documentation.

Stripe includes docs in career ladders and performance reviews

In addition to creating support systems, Stripe also encourages developers to write documentation by including it in engineers' job ladders.

Before joining Stripe in 2017, Nunez oversaw all of Uber's technical content. In order to encourage developers to prioritize documentation more, he worked with an engineering leader to add documentation expectations in every level of an engineer's career ladder. Immediately, engineers began writing more documentation.

When Nunez joined Stripe, he brought this strategy along with him. “I took this step in the first week. I put one line about documentation on each level of the job ladder,” he said in an interview.

But Stripe doesn't just include documentation requirements in their job ladder. They also follow up by assessing engineers' documentation writing in performance reviews.

“Managers need to take this requirement seriously come performance review time,” Nunez writes. “Set the expectation in the interview phase that documentation is an integral part of the software development expectations at your company.”

Some managers even publicly recognize engineers who write high-quality documentation. At one point an engineering manager at Stripe included a ‘doc star of the week' in her weekly updates to the broader team.

My takeaway: Rewarding people for creating high-quality documentation encourages your team to constantly add to, and improve, your documentation. It also ensures that the labor that goes into creating docs is never wasted, nor does it go uncelebrated.

Stripe builds docs that feel like a product

“Our product docs are designed to feel like an application rather than a traditional user manual," Ryan Paul, Stripe's current Head of Docs wrote in a blog post last year.

Instead of relying on large blocks of text, Stripe's docs use custom features to improve interactivity and usability. Users can customize the docs to display code in their preferred programming language and see code examples in Node, for example.

Stripe's docs are also interactive and tailored to individual users depending on where they are in their onboarding process . For example, a user's API test keys are automatically added to code samples, a subtle detail that makes for a great user experience.

The company recently built an entire Markdown-based syntax called Markdoc to make their docs more manageable and flexible. As Markdoc creator Ryan Paul wrote, “Our team at Stripe spends a lot of time thinking about the authoring experience and how to get it right. In many ways, Markdoc is the embodiment of our obsession with building a better authoring experience.”

It's tempting to think that Stripe can only afford to do this because of their size. After all, the company is worth $50 billion. But Stripe has been building docs that feel like a product since its earliest days.

Looking at Wayback Machine's snapshot of Stripe's website in 2011, one year before the company raised their Series A, you can see that they already had docs that included a working API key and support for multiple languages.

Stripe's history is evidence that every company can build beautiful docs as long as you make it a priority.

Your turn: Whose docs inspire you?

Documentation is not an easy problem to "solve". Creating Stripe-like documentation requires you to invest time and commitment into building a culture that values writing and documentation. It also requires you to introduce systems and processes that support your team in writing.

What do you think makes Stripe's docs great? What company sets your gold standard for docs and why? Let me know on X (formerly Twitter).