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.
Summary:
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)
Scribbles:
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.
Challenges
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
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