| description | 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. |
|---|
{% embed url="https://youtu.be/uFGCaZmA6d4" caption="Video" %}
- 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)
- 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.
- 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.
- 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?
- 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.
- 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.
- 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.
- 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.
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.
- This is convincing other technical writers that Docs Like Code is the way to go! Okay, no one got that.
- So this is return, the elixir is the Holy Grail
- Docs Like Code has been the Holy Grail.