 Hello everyone and welcome to my talk today. I really appreciate you all taking the time to be here with me And I just wanted to start this talk by thanking all the organizers of this conference And especially for one thing and for that's for encouraging first-time speakers This is my first ever conference talk, and it's also my first ever conference talk proposal that I did send in But it's also actually my first ever tech conference that I attend So I can tell you that I am really really excited to be here with all of you today and The goal here for me is really to talk about how we have been unlocking the potential of Engineers collective knowledge and how you can do the same within your organizations My name is Emma. My pronouns is she her hers You can find me under Twitter and on Twitter github or other platforms as well under Emma Indahl I'm based in Gothenburg, Sweden, and I am a web engineer for Spotify And I've been there for around two years now, and I work specifically in a team who are focused on technical documentation But also discoverability in a on backstage and so when I'm not working on that I'm also super super passionate about teaching kids to code So I'm a volunteer imagine mentor for a startup called a magic labs But let's dive into Spotify's engineering organization a little bit. We are around 1,600 engineers distributed in autonomous cross-functional teams We have around 14,000 plus software components and we have around 1,400 microservices in production and These numbers are great But you know the more these numbers are growing and the more the need for to unlock the potential of engineers Collective knowledge are growing as well And When I say collective knowledge, what do I really mean by that and so Well, I I presented in the previous slide some numbers around that we are 1,600 Engineers internally and we have around for 1,400 microservices Services in production And so as you might have been able to figure out already all of these engineers are not working on the same microservices all the time so That means really that different engineers and every individual working for Spotify knows A little bit about a very small part But together we know a lot So if we can avoid siloed knowledge and instead One person can contribute with what she knows about a service or Another person about what he knows about a website And a third person about what they know about their data pipelines You know, we're starting to build up this space of collective knowledge and So why is this so important then? um The simple answer is really speed Because if we can speed up our engineers and make sure that they go from stuck to unstuck faster They can focus on their products and their end users instead of like issues. They're running into daily And we're now starting to see a more distributed workspace as well So we will continue to do after the pandemic as well And this means that you're not able to like just run by your team members desk and ask them a question that you have on top of your of your head So the the need for collective knowledge is growing there as well But to be able to capture this collective knowledge we need to remove the friction for the producers and with producers here, I mean the people who are writing the content and It's really about so that the engineering knowledge can get shared within organizations And i'm gonna tell you how we did that Uh internally at Spotify And how we are now making it possible for you to do the same in your organizations And first thing first, I wanted to guide you through a story Um, it's it's not really a story. It's more about me talking about myself in third person But it's really about so that we all can get on the same picture and understand and dive into the problems and friction and That comes up when when trying to contribute to collective knowledge And this is specifically in the format of technical documentation So Emma has a new feature she has built and she goes through her everyday workflow Looks something like this. She has been writing her code Committing her changes creating a new pull request and the already configured continuous integration environment gets triggered Tests hopefully passes and she's emerging the the branch into a master and her code gets deployed into production She feels super confident in shipping changes and new features this way because there are not much friction for her to do so But she also feels that she cares about this new service and this new feature She's built and she wants to contribute to this collective knowledge by sharing what she knows because she's she is the expert Right. She have been working for this for a long time and she wants to contribute back So and she also knows that um someone else in her team might work on this in the upcoming weeks or months And if she can get that person up to speed faster, uh, it's going to be worth it, right? And so she's starting to think a little bit about how can I produce this documentation for this new service and Where can I start like what tool should I use? And she gets to a point where she feel like Like no matter what path I take I need to Move out from my everyday workflow to do this So she starts writing the documentation in a new workflow, of course. She have been she have left her Everyday workflow into a new one and she starts writing the documentation some tool that she took a decision around She stored somewhere maybe in the confluence if if she decided to use that or maybe in google drive If that was what she she decided to write the documentation in And then she wanted to just share the the documentation with some team members And so she just copied the link to the Documentation and and then just share it with them And then six months later when you know the documentation has been around around for a while Emma's team members gets back to her and asking where where she did put the documentation that she wrote And if she can share it again And Emma first needs to think about where did I actually put the documentation because she didn't really remember herself maybe and You know she needs to go and find it and then she can get the link again and you know share it to to our team members again for the second time and This time around Emma did actually produce documentation Even though she had to switch context go take a lot of decisions about tools to use where to put it where to store it In the meanwhile and leave her everyday workflow to actually produce the documentation But you know all these extra steps that she had to take will probably stop her from doing it next time And especially since like her team members couldn't even find the documentation without asking her a second time where she did put it So she spent time on time writing documentation that no one could find And the end result of this is that the knowledge Emma sits on will not get shared within the organization And if we take take just one second and think about cncf You know cncf technologies Let organizations and individuals develop software more effectively And removing friction of writing documentation contributes to this too So what if we can just merge these two different workflows into one By tightly coupling the process of writing documentation With the developer workflow So that it becomes as frictionless and natural as shipping new features So let's go back to the first workflow because this was the workflow that Emma felt confident in There were not much friction for her to ship changes this way. So let's go back to that But this time Emma can actually write Documentation in markdown files at the same time. She's writing her code So she can commit her documentation changes at the same time. She's committing her code changes And when the already configured continuous integration environment gets triggered The new documentation is generated using from markdown to html using some static site generator As well as published to some storage in the cloud And the only thing Emma needs to focus on here is to stay in her everyday workflow And all other additional steps are abstracted away for her And then one month later, sorry six months later when the documentation has been around for a while Emma's fellow team members doesn't even Need to go back to her asking where the documentation can be found Because it's so well known within the organization that all internal technical documentation Lives in one single place and can be discoverable there And that place is something we call tech docs and we will go into that a little bit later in the talk And the end result of this then Amazing work in tech docs. It was so easy to set up. I will give you a kitten spotify engineer We did not get a real kitten or we haven't got it yet at least But we did end up with a happy spotify engineer who did contribute to this collective knowledge Because it was so easy to set up and get started And some of you have maybe already heard of this as something called docs like code That was something that we adopted and built out within spotify But it's really just one half of solving the problem It did remove the friction To produce and share knowledge in the format of technical documentation In the same workflow as you were shipping new features But backstage solves the other half making it collective and discoverable in one place But what is backstage then? If you have never heard about backstage before it spotifies internal developer portal A developer portal that enables engineers to create manage and explore software components And the idea is really to centralize and simplify end-to-end software development with an abstraction layer on top And that's it's on top of all your infrastructure and developer tooling And so backstage comes with specifically three core features Of which plays an super important role into solving this problem So i'm just going to dive into the details of these three core features a little bit more And what role each of them have in this experience So the first core feature out is the scaffolder And the scaffolder lets you create new software components based on standard templates And these standard templates can be configurable with tech talks already from before So that your engineers who are creating a new software component out of these templates gets a documentation site up and running Automatically instead of having to configure it all themselves And so who are responsible for putting these templates together Some of them you see here in the picture are actually available for you, but you're of course Free to contribute with what you your organizations What what your organization need? With your own templates really And so let's say that we want to create a standalone documentation component because maybe it's not necessary Doesn't need to be attached to a specific service. Maybe it's meant to be onboarding guide or a Or documentation that spans over multiple services So you just start with filling out some information Such as name description owner of the software of this documentation component As well as where to live what location meaning that where the repository should live really And this process just creates a new Repository for you with all configuration needed as well as some default documentation in the docs folder And So now we have the content we have some default documentation already Because we created a documentation only component through the scaffolder but Where can I actually read the documentation then? Well, the second core feature is tech docs And I've mentioned it briefly briefly before but tech docs is really the place in backstage Where documentation can be discoverable and consumed It's really one place for all internal technical documentation So for example here, we can see a collection of all tech docs sites within the organization And right there we can find the documentation component that we just created in a preview step And by navigating into it we can start reading the documentation that has already been generated for us And last but not least another important core feature of backstage when it comes to unlocking the potential of engineers collective knowledge Is the software catalog And the software catalog in backstage is a way for you to discover All services within the organization that either you own or another team owns Of course also the documentation that is attached to it So let's take a look at what that looks like as let's select the service for example We can just navigate to the docs tab And right there close to the service that we own or another team own We can quickly just start reading the documentation to it and so We didn't just want to unlock the potential of engineers collective knowledge within spotify But we also wanted to unlock this for other organizations as well Therefore we started to open source tech docs as one of these three core features of backstage But you know, we quickly realized that just because we use a specific set of infrastructure behind tech docs It doesn't really mean that other Engineering organizations are using the same So we came to the conclusion after some discussions in the team, but also with the community That we wanted to focus on making tech docs for all So that no matter what technologies you are using from the cloud native landscape Tech docs should be configurable to your needs and solve this problem for you And let's take a look at a few example of that For example with less than 10 lines of configuration in yaml You as an app integrator of backstage can configure the tech docs plugin to publish generated documentation To the cloud storage of your choice And here are three examples such as google cloud storage amazon web services s3 and ashore blob storage Another example of that is that you as an app integrator can set up templates available through the scaffolder that i showed before and You know that core feature where engineers can create a software component out of already existing templates If you pre configure your templates with the source code provider of your choice You are abstracting that configuration away from the engineer. So that again, they can focus on Contributing contributing to this collective knowledge instead of the configuration behind And this slide is just something that I wanted to show you to list all our Currently supported source code hosting providers as well as file storage providers And if your underlying infrastructure and tools are not listed here We are more than happy to collaborate with you to get it on the list And so if we just take a step back and look at this picture again that I showed in the beginning of the talk We can see that this light bulb in the middle can be replaced with backstage Backstage makes it possible to have one centralized place for collective knowledge And again, if we think about tech tech talks, which is the key part into producing and consuming internal technical documentation Knowledge is more than just documentation Maybe in the format of shorter questions and answers Maybe you have a stucco willful instance put together internally That you're collecting questions and answers within the organization So therefore we develop features on top of tech talks for example to the left here You can see the stucco full widget neck that you have next to your documentation so that you can get exposed to Questions and answers connected to the documentation you are reading And remember, you know collective knowledge only happens when more than one person contributes Therefore we have developed We have focused on like closing the feedback loop so that the consumer of the documentation Quickly can just highlight a piece of text and open a new issue and contribute with what they know And keep the documentation up to date And these are by the way features that we have not open source yet, but are definitely on our roadmap And maybe now you all sit here and think collective knowledge is not possible without great discoverability And I told you before about ms team members who were not able to find ms documentation Just and just because we have one place for this collective knowledge It doesn't mean it It doesn't mean it is easy to find Especially not when you're about to browse around 4 000 tech doc sites that we currently have internally So I agree something is really missing here So we have not been unlocking the potential of engineers collective knowledge without leveraging a good search So that's why we are currently open sourcing and building out the search plugins So that one for example from the tech docs plugin can Can index the documentation and make all documentation discoverable through backstage search And with that added on top of these three core features Of backstage we have been unlocking the potential of engineers collective knowledge Both by removing the friction of contributing to collective knowledge As well as making it collective and discoverable through one single place And you know you can do the same because it's all open source or in the progress of open sourcing at least So thank you all for listening to my talk today And if you are interested in the project head over to backstage.io Where you can hopefully find all information you need to get started And you know don't hesitate to contact me if you want to you would like to hear more about this Or maybe you want to tell me about your stories But before we end this session, I wanted to give you a Some time for any questions that are on top of your mind And hope that I can answer as many of them as possible Thank you all