00:00:05.759
Let's move on to our next speaker, Bill.
00:00:06.720
Bill is a developer at Spotify, a big fan of developer happiness. I am a big fan of developer happiness as well. That's my happiness.
00:00:10.400
Quite a student of the subject, he's a developer advocate and he's here to talk to us today. We're super thankful to have him, so let's give a warm welcome to Bill!
00:00:35.560
I want to talk today about how Spotify is making internal documentation better, easier, and less boring. I work a lot with documentation. I've worked as a developer advocate and also built APIs, so documentation has been at the heart of everything I do.
00:00:58.640
To be fair, it's probably at the heart of what everyone does; we all rely on documentation. Just to clarify, this is very much about technical documentation, not vacation policies or anything like that.
00:01:18.159
I might as well start with an introduction. My name is Bill, I live in Sweden and am a software engineer at Spotify. I'm originally from Manchester, England, although my accent is a bit messed up these days.
00:01:35.760
Has anyone here been to Sweden? Cool! Then you know how amazing this country is. I also used to be a developer advocate, and I worked a lot with Rails, which is one of the reasons I'm here.
00:01:43.280
This talk is a new one; it's the first time I've given it since it’s been a while. Please bear with me. Today, I want to discuss developer experience. Hopefully, it’s applicable to everyone. I will try to include some Ruby-related content as well, but it revolves around general developer experience. If you work with other languages, this should be relevant to you.
00:02:06.160
Lastly, this is an opportunity for knowledge sharing. Many people here want to share what we know because, let's face it, we need to work together on these issues. The structure of my talk will start with the problems we're facing, followed by some inspiration we’ve had and the approach we ended up taking, the impact we've seen, and then takeaways.
00:02:31.400
Let's start off with the problems. Documentation is not a new issue. Since the inception of software, we've thought about documenting it. In the past, we used to have books for one piece of software, but now we typically only have a README file for many projects.
00:02:55.920
It's something that's always been on people's minds, but isn't it supposed to be easy to create documentation? We have many tools at our disposal. For Ruby, there's Jekyll, while in the TypeScript world, there’s TSDoc which automatically generates reference documentation from code annotations. So, by using these tools, shouldn't it be easier than ever to publish documentation?
00:03:29.200
If we consider the Ruby world, we have tools like RDoc where you can copy and paste GitHub issues into the documentation. This used to be very popular! However, these tools are usually designed for static websites, not specifically for addressing internal needs.
00:05:03.120
Most of these documentation tools cater to external needs -- branding projects and creating fully-fledged websites that demonstrate how your system works -- but they often overlook internal needs.
00:05:23.039
Internal documentation needs to address things like ownership and the history behind projects. Unfortunately, many open-source projects don’t provide this information, which can make understanding systems challenging.
00:05:46.240
At Spotify, documentation exists in many different places. Generally, people don’t want to create documentation websites when they are building software internally. They want to provide useful documentation without building a whole site around it. Externally, things are different; we would like to make comprehensive documentation.
00:06:13.680
Only a small fraction of software within Spotify uses GitHub pages for documentation. This scenario can make managing documentation a challenge.
00:06:46.800
Then, we have Confluence. While many companies use it, it’s not necessarily a solution for technical documentation. Many companies believe it fits their needs. However, it’s generally not a fit for developers.
00:07:11.760
There’s a challenge at companies like Spotify where things move quickly, and prioritizing documentation work can be difficult. Often, documentation is put on the backburner until much later.
00:07:28.240
This leads to many people needing to navigate a complex code base just to contribute. Spotify is known for its agile development framework, but we face challenges with roles in our teams, resulting in various people having different responsibilities that can ultimately slow down the documentation process.
00:08:15.440
The demand for documentation today is high, yet many engineers are hesitant to write anything. While I have been involved with documentation work for some time, many engineers lack confidence in producing quality documentation.
00:08:54.280
The infamy surrounding documentation issues means that, internally, we’re often under pressure to get things right. Naturally, that hinders the speed at which we can contribute to different projects.
00:09:33.280
With the need to communicate a clear flow of information internally around documentation, we have noticed these three major barriers: a high barrier to entry, issues with discoverability of the documentation, and trust problems.
00:10:05.800
Documentation is inherently a trust-based system. If engineers cannot trust the information they see in documentation, then it can lead to poor experiences and inefficiencies. We want to foster an environment where developers can feel confident in navigating the resources at their disposal.
00:10:54.760
So, in 2019, Spotify attempted to solve these issues. We want to allow engineers to be more effective and productive, eliminating barriers and encouraging a more efficient work environment.
00:11:29.600
We had initial conversations around the tools we might want to use. Instead of creating additional software, could we enhance our existing use of GitHub? It seemed a good idea since GitHub has effective tools that allow documentation to be co-located with the code.
00:12:00.000
Still, we faced challenges with ease of updating. We didn't find a complete solution using GitHub alone, particularly around trust and maintainability.
00:12:38.640
Next, we looked into a library that leverages Google Docs. The concept here is solid; it automatically categorizes and organizes documentation in shared folders. Though not immediately applicable to our API documentation, we believe it holds potential.
00:13:12.800
Another tool called Readme is commonly used, particularly for outward-facing teams, engaging developers actively. However, no single team has ownership over documentation, which results in gaps and inconsistencies.
00:13:52.240
I want to share a quote: ‘Documentation is a love letter to your future self.’ Unfortunately, bad documentation becomes a hate letter to your future self. This sentiment drives a pivotal change in how we view documentation.
00:14:29.760
We aren't looking for anything radical. We are simply trying to tackle the problem with concrete solutions. One concept we encountered was a book called Dark Side Code by Angela. She discusses treating documentation just like code. This includes automated parts that are generated and code samples getting tested so that documentation is part of the developer workflow.
00:15:30.480
This idea has inspired us to develop a tool called Tech Docs. This tool offers a centralized location for documentation across Spotify, creating an intuitive experience for engineers. Using open-source projects, we built this within a week to ensure we could leverage our existing knowledge.
00:16:53.520
Tech Docs allows documentation to be integrated within Spotify’s software ecosystem, linking closely to code, driving down the barriers to access. We designed it so engineers can access documentation easily while coding, providing them immediate insights into project needs.
00:17:44.480
Our aim remains to foster a documentation culture that remains continuous and updated. We prioritize making it easily available for engineers, with tools designed for their experience, allowing for rapid access to critical information.
00:18:31.560
This ties into broader standards we can create across various aspects of our workflow, promoting seamless communication around documentation expectations among teams.
00:20:53.760
There are two documentation types we need to be aware of -- system documentation and service documentation. Most engineers understand how documentation works today, but system documentation holds significant potential value as we standardize how we explain services and tech.
00:21:33.200
By focusing on documentation of error messages and promoting information that can alleviate confusion, we can ultimately enhance the experience for engineers, propelling them toward best practices and reduced friction.
00:22:52.080
In solving our discoverability issues, we want to encourage documenting key concepts or error messages in a direct manner that offers engineers immediate access to knowledge without further research.
00:23:39.520
Additionally, we are working on promoting predictable URLs and consistent URL structures, making it easier for engineers to navigate their documentation. Creating a culture that acknowledges the importance of effective documentation also assures everyone understands the tools at their disposal.
00:24:37.200
While we are exploring automating how documentation is maintained and updated, we also prioritizing ensuring reliability and accuracy. A constant feedback loop will help us gauge our impact on this initiative.
00:25:15.680
Through our ongoing efforts, we aim to cultivate trust between code and documentation so engineers can feel confident about the resources they are accessing.
00:27:01.680
As I conclude my presentation, I encourage all of you to consider the perspective and importance of documentation within your teams, moving towards an environment where we prioritize quality and accessibility.
00:27:43.760
Thank you so much for attending this session!
00:28:37.880
But never let it be said we're not selfish. Here's some of our booty that we found. Thank you so much!