# Solving internal technical documentation at Spotify {% embed url="" %} Video {% endembed %} ## 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. ‌