Solving internal technical documentation at Spotify

Gary Niemen share their story of how their approach to documentation has changed at Spotify, drawing parallels with Joseph Campbell’s Hero’s Journey framework.


  • The Hero’s Journey and how they are solving technical documentation at Spotify.

    • treating docs like code. ‌

  • What have we learned?

    • Keep focused on the key problem

    • Keep the solution simple so it just works?

    • Fiercely optimize for the engineer.

    • Enable others to build on the platform

    • Standardize and centralize.

  • What’s next?

    • They need to work more on trust and maintenance.

    • Open-sourcing TechDocs

    • They haven't yet solved in-code documentation. (They may have by now -- given its 2 years from the conference)


Ordinary world

  • At Spotify, they have about 1,500 engineers and a lot of the engineers are making tours or platforms for other engineers at Spotify.

  • There’s a great need for technical documentation.

  • Spotify’s culture of the teams can work in the way they want, it happened over time that when teams realized they wanted to do some technical documentation

    • they would do it sometimes in Confluence

    • they would do it sometimes in Google Docs

    • There was tons of technical documentation spread everywhere.

  • And of course, then other engineers looking for this documentation, couldn’t find it when they needed it.

  • They had a search engine, but it didn’t work that well. And it broke after a while, so it was a sort of chaotic situation.

Is this a problem worth solving?

  • Not finding the information that you need -- number three blocker. So yes, it’s a problem worth solving.

  • Their technical writers were spread around the infrastructure teams and they were solving smaller problems within the individual groups.

  • They weren’t solving the big problem for Spotify at all, they were solving individual problems.

Call to adventure

  • Their call to adventure started when one of their writers spotted a talk that Google had done about three years ago, at the docs conference.

  • Google had exactly the same problems that had been spotted in Spotify's organization

  • Coincidentally, they were about a week away from Hack Week at Spotify.

    • they decided to try and just do something like what they saw Google had done.

  • And they did that and it worked out quite well, and they showed it off to people.

  • What would it take to do this really well here at Spotify?

Refusal of the call.

  • Docs Like Code approach.

Could I give up my craft, in a way, that I’ve been working with for years? And of course the answer is yes, otherwise I wouldn’t be here today.

The mentor.

  • There were three technical writers in a team.

  • And they had a hypothesis.

  • They did some user research to validate the hypothesis that they had, not only for the solution but for mainly the problem.

Crossing the threshold.

  • They got started,

    • They had their team

    • They were gonna build something like what they had done in Hack Week and something like the Google thing.

    • And so they spent weeks and weeks with complex designs and processes, complicated architectural design and this was it.

    • Within a couple of weeks, they got out an alpha version of what they called TechDocs.


  • Discoverability and findability

    • Findability, you know what you’re looking for, that’s search.

    • Discoverability, you don’t know what you’re looking for, but you want to discover it, that’s a problem of technical documentation.

  • Trust, how can you trust…

    • How can you trust what you find?

  • Maintenance

    • It’s very easy to create documents, but or documentation, but how do you maintain it afterwards. That often gets forgotten.

  • Feedback loop

    • That is about somebody making comments on a piece of documentation, that those comments would get to the one who, or the team who owns that documentation and they will correct it and then you get a feedback loop.

  • Hidden knowledge

    • That's many engineers having lots of knowledge that’s in their heads and it’s not shared.

  • Ownership

    • is a bit connected to no handover process.

    • Documentation has to be owned. If it’s not owned, it will absolutely decay over time.

    • And then a handover process needs to be in place otherwise you won’t have ownership eventually.

  • Used and useful

    • Teams who create documentation really wanna know that it’s used and that it’s useful for their own, you know, they put a lot of work into putting some documentation up and they need to know.

  • Adoption and engagement

    • There are often different use cases, and different needs, you have to think about that you can’t just ignore that.

  • Engineers get stuck and they want to use documentation to get unstuck,

    • Then you wanna help them fast.

    • They want to get unstuck fast, so that really is the key problem underneath all this.

Docs Like Code Plus

  • Basic how-to-do tech documentation at scale.

  • Enabling the engineers so just make it super easy, the documentation is as close to the code as possible.

  • It’s in markdown, so it’s super easy and they provide navigation.

  • Super easy for engineers, in line with their workflow completely in the tools that they’re using every day.

  • Information card (trust card eventually)

    • For each documentation site, you’ve got the owner, they get that from GitHub, the doc was last updated, they get that from GitHub, the open issues again.

  • Feedback loop,

    • Users click that and they go directly into GitHub and they can submit a PR

    • Users create and highlight a piece of text and select that for opening a GitHub issue.

  • Doc home page

    • Addressing discoverability and findability.


  • Reward is the impact that they’re having in the organization and the love that they get for TechDocs.

  • Docs Like Code plus -- they’re really having an impact on the organization.

  • Lots of positive feedback.

The Road Back

What’s their success factors?

  • A cross-functional team

    • Was absolutely essential.

    • They were solving a real problem in the organization.

  • Embraced Docs Like Code

  • Quick development of a minimum, lovable product.

  • Good adoption

  • Collaboration

  • They had a clear and inspiring vision.

The Resurrection

  • This is convincing other technical writers that Docs Like Code is the way to go! Okay, no one got that.

Return with the Elixir.

  • So this is return, the elixir is the Holy Grail

  • Docs Like Code has been the Holy Grail. ‌

Last updated