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. ‌