API Documentation
Making Tech Documentation Better, Easier, And Less Boring

Summarized using AI

Making Tech Documentation Better, Easier, And Less Boring

Bilawal Maheed • June 01, 2021 • Rotterdam, Netherlands

In the presentation titled "Making Tech Documentation Better, Easier, And Less Boring", Bill Maheed, a software engineer at Spotify, discusses the significant challenges surrounding technical documentation and how Spotify aims to improve it. Bill emphasizes that while software development is often prioritized for efficiency and effectiveness in coding and testing, documentation often remains neglected despite being crucial for developer success. Key points addressed include:

  • The Importance of Documentation: Documentation is essential in software development, serving as a primary resource that developers rely on.
  • Challenges in Documentation: Bill identifies several problems facing documentation today:
    • High barriers to entry for creating and accessing documentation.
    • Discoverability issues, where engineers struggle to find relevant documentation.
    • Trust issues, as unreliable documentation can hinder developers' confidence.
  • Current Tools: Many common tools like GitHub, Confluence, and others cater primarily to external documentation needs, leaving internal documentation insufficient.
  • The Need for a Cultural Shift: For effective documentation practices, Spotify aims to foster a documentation culture that prioritizes both quality and accessibility.
  • Tech Docs Solution: Bill introduces "Tech Docs", a centralized tool designed to streamline documentation processes within Spotify. This tool integrates documentation with code, allowing engineers to access information directly while coding.
  • Continuous Improvement and Reliability: Future goals include automating documentation maintenance and establishing a feedback loop to measure the system's effectiveness.

Ultimately, Bill concludes by urging the audience to recognize the critical role documentation plays in their teams and to strive for a culture that values and actively maintains clear and accessible documentation.

Making Tech Documentation Better, Easier, And Less Boring
Bilawal Maheed • June 01, 2021 • Rotterdam, Netherlands

How We’re Making Tech Documentation Better, Easier, And Less Boring

Engineers optimize for scale. We think about writing the “best” code, designing non-flaky tests to give us confidence, and adopting the latest and greatest - but why do we still fail to write, maintain, and improve our docs? Given we all rely on docs, what went wrong?

Bilawal Maheed - https://twitter.com/bilawalhameed
EuRuKo 2019

EuRuKo 2019

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!
Explore all talks recorded at EuRuKo 2019
+12