Stripe engineering’s second brain: Trailhead origins

Stripe has the best documentation in the world. At a certain point, Stripe's docs were 10x better than the average documentation set: accurate, well-designed, well-organized, consistent. As public docs, anyone could go look at Stripe and emulate their practices for their own documentation. As an industry, everyone's docs have gotten pretty good.

Not many people know this, but Stripe's internal documentation is 100x better than the average company. To accomplish this, first you start with the desire to build a decades-long company, then you build a writing culture to spread information and document historical context, then you build the best tools to support this culture at scale.

This approach worked out beautifully in a world where infinite agents are starved for high-quality context. Stripe's trajectory—with all of its juicy context and secrets written down—has never been greater.

Start of the trail

Engineering has its own documentation system at Stripe, called Trailhead. Using Stripe Trailhead is like stepping into Diagon Alley. Behind Stripe's firewall, you're connected to all of its internal data to provide yourself and your agents with reliable context to get your job done. Because it's private, only Stripe employees can see it. The rest of the world can't emulate this system like they can for its public docs. And it's a core piece of the context engine powering its coding agents, Slackbots, and agentic search.

There's very little public information about Trailhead.

A short excerpt in the Pragmatic Engineer newsletter: https://newsletter.pragmaticengineer.com/p/stripe-part-2

And a public talk by Alistair Gray:

https://www.youtube.com/watch?v=DxbXKLl-URo

The origin of Trailhead's was born out of necessity, driven by pain.

The summit before the ascension

On a Sunday night in 2021, I got a Slack ping from a legendary Stripe engineer, Sidd. He had an ongoing dialogue with our CTO and CPO about the urgency of Stripe's knowledge bottleneck problem.

Sidd: "dps and wg want to solve internal docs asap with a full-day summit. Starts at 7am thursday, and they want to leave with a clear plan on how to solve this problem. Can you come?"

Me: "Absolutely."

Tuesday night rolls around, I get another ping.

Sidd: "Ready for the summit on Thursday?"

Me: "Hell yea, very excited."

Sidd: "Cool, because you're going to lead it."

And so began my final dream project at Stripe: building our own internal docs platform from scratch.

Docblocked

The main problem with our internal docs was that many engineers refused to use Confluence. They preferred to write in Google Docs or Slack. But Google Docs didn't have good markdown support, code samples, or integrations. And we had a data retention policy within Slack that meant information couldn't live there for very long.

This meant information was scattered everywhere, and people couldn't find it.

We used Confluence, Google Docs, Hackpad, Dropbox Paper, and markdown files to store documents. Nobody could find anything, search was choking on all the different sources, and we were all feeling the pain growing to 10,000 people overnight. It was showing up in the metrics. New hires were onboarding slower and PR velocity was going down because engineers had to spend extra time supporting their new teammates.

Build vs buy

Patrick and John always had a clear goal: have the best developer experience in the world. The UX, the brand, the PLG, the ROI. Having the best developer experience required having the best docs. To have the best docs, we needed the best tools. We absolutely did not want to build our own tools. We would've loved to have just purchased something and spent more time on customers. But no tool came close to what we needed. So we took things down to the studs for our public docs, even creating our own flavor of Markdown.

When we decided we needed to have the best internal docs in the world, we absolutely did not want to build our own platform. We knew how time consuming it was, because we just did it for our public docs. For our public docs, the architecture and design and prototyping took 3 months, and the migration took 6 months. At the time, doing this in 9 months total was blazing fast.

Confluence

We knew Confluence was hopeless. We tried to extend it at Uber and the API was a nightmare as was the support from their side. Even so, we took another look at extending it at Stripe and deemed it a non-option.

Dropbox

We spent hours and hours with the Dropbox team at their offices and ours, providing them with input to build the ultimate knowledge platform around Dropbox Paper. We even saw mock designs where they had a great plan to build it out. But it ultimately wasn't prioritized by their top leadership, and it didn't get built.

G Suite

Through our CISO, we got intros to the upper echelons of G Suite. We told them we just needed markdown support and knowledge management capabilities to make it the perfect docs tool. After the first conversation, we got complete crickets from the follow-ups. They were not interested.

Notion, Coda, etc.

There was a long-tail of workspaces that weren't performant, secure, or engineering-forward enough for us to consider. And we wanted something opinionated—not a choose-your-own-adventure wiki.

Mapping the trail

When building our internal eng docs from first principles, we kept it simple.

make it secure

make it performant

make it easy to create things

make it easy to find things

Where to begin with building Trailhead? With a document of course.

I outlined the vision for an internal knowledge platform, from authoring to discoverability.

Ian, my engineering counterpart for the Docs organization (yes, we had an entire org related to Docs—and it was one of the most talent-dense orgs at the company, I say unbiasedly) translated the vision into a clear roadmap to help us get resources from leadership. A year's worth of work, outlining a decades-long vision, encapsulated in a 3-page Google Doc.

Next, it was time to build the all-star team.