Documentation as Empathy

Sure. Could you all hear that? Alright, well you can hear it again.

So the last time I was in this room was five years ago. And it was to see Bay Lafleck perform the music that you just heard. And he had traveled around Africa in search of the banjo, the root of the banjo, and he found these amazing musicians And then he took them all and went on tour in the US and came to the literal center of the country in Lawrence, Kansas, on this very stage. And I think it's really just amazing that Django started in a basement right next door, spread across the entire world, and then brought us all here together today. And then I also five years ago did something that is slowly starting to spread across the rest of the world. And I bring people together in a different room in Portland, but you get the idea.

So today I'm going to tell the story of kind of how I ended up here in Lawrence, where I've gone from there, and kind of what I learned about documentation along the way. So seven years ago I was in university, I was a junior, and I was uh I had an internship, and I was writing Pearl for the military. Those of you that know me makes that doesn't make a lot of sense, right? Um and I was like, all right, I need to change something. I'm gonna go learn Python, because I've heard it's amazing. I'm gonna learn Django because that's what you do to learn Python, right? Um and so it all really started with a PDF. I downloaded the Django documentation as a PDF and I went on Thanksgiving break with my family and I read the whole damn thing.

I was like, this is amazing! It's teaching me web development, it's teaching me Python, and it's teaching me Django. Like all at once. It was pretty magical. Back then the Django docs were only about 300 pages. Today that would be a little harder because they're currently clocked in at about 1500 pages. So the story might be a little different. It might be a you know a week-long break. Um and so I was like, I really fell in love with Django. And kind of crazily enough. In uh February 20th, 2008, I was like, I need to find a job. I'm gonna start my job hunt, and it's gonna be amazing. And literally the next day, Jacob posts a blog post about leaving the journal world. And if you haven't read it, I highly recommend it. It's this heartfelt, like it's the hardest thing I've ever had to do. And I was just like, how much more of a sign do I need that this is the job that I should go take?

And in in the blog post, he's like, the unofficial job description is build cool shit. And like as a like university student, you're like, that sounds amazing. That's not the real life they told me about. That's like this fake weird life in Lawrence, Kansas that nobody believes exists. And just so you don't think that I'm making this up to fit the narrative of documentation because, you know, that would be very convenient, I actually wrote a blog post in a co-op house about half a mile from here, the day before I'm starting my job, like freaking out, kind of telling the whole story. And I actually in that I was like, I read this damn PDF and I fell in love with Django. So you can go to that URL And it is it has been there. It's in archive. org. It's this is a true story. So I landed here in Lawrence, Kansas, not quite knowing what on earth I'd gotten myself into.

And I landed into something that just had this amazing documentation culture. Um kind of as Jacob said a little bit The Python and Django worlds care about documentation, I believe, more than any other language community that I've seen in the open source world. And the way that this really comes across is people don't use projects that don't have documentation. And a lot of communities will say, oh, there's no tests, I won't use that code. But in the Python and Django world, if a project doesn't have documentation, people won't use it. And those kind of cultural kind of like milestones and like things in a culture that kind of embed that love and importance of documentation are incredibly important. And another way that you know kind of Python really loves documentation

is I've been looking for five years for a documentation tool that's better than Sphinx. It doesn't exist as far as I know. Sphinx was actually created to document Python. It was created so that they could have a real tool to document the language. And then they released it as open source, of course, and now it's used in Django. Um Read the Docs is based on it. But it really came out of like literally Python core. And it's still, in my opinion, the most advanced and best documentation tool that exists. Even Microsoft today is using it for all of their open source documentation. If that, you know, if you need any more like buy-in. And so I landed in Lawrence and I started doing all these little side projects, right? And so I'm like, I they expect documentation. I guess I should start doing that.

You know, they don't teach you docs in university You know, you don't maintain code. It's about tests or documentation. So I've wrote a couple little, you know, silly utilities. And then I actually wrote like a project, the Django Reasonable App Docs that were, you know, a pure documentation project. Um and so I wouldn't be writing documentation unless I was kind of landed in the Python community. It was just expected, and that's what you did. And so I would like to thank Jacob especially. Um his 2009 posts uh on writing great documentation are still kind of the the canonical example of like Telling people how to write good documentation, which is kind of terrifying that it was six years ago. But I think I was like reading the Rust docs the other day and they linked these set of posts. It's still kind of like the gold standard.

And then in 2001, during the Django Dash, which is a 48-hour coding competition, you know, we had all this documentation we'd been writing. They were sitting on a server and a cron job was running every five minutes to like pull down the code and run make HTML and like keep the docs up to date. So we're like, we can solve that problem in 48 hours. You know, we're web developers. We have webhooks. We have GitHub. Like, let's build something that's like so obvious to us. And then in 2011, Jacob also gave a really great talk at PyCon where he kind of espoused a lot of this documentation culture stuff. Um which is basically just I'm regurgitating here today in a lot of ways, but it was just such a big influence and it really kind of shaped how I viewed documentation in the programming world.

But Read the Docs, when it started out, was really a tool to reduce friction. It was like we have these documents, we want to keep them up to date. Let's build a tool that like solves that very kind of specific problem. You know, I didn't really understand documentation at a deep level. I was just like, I have a problem, I want to scratch my own itch, I'm gonna like solve this for myself. Um and I just want to talk a little bit about kind of the origin, uh just for a second. It was actually founded here in Lawrence, as Jacob said. The idea, I believe, was down at La Primataza. None of these pictures are the actual dates, but I did want to say that As you can see there, Malcolm is circled and he was a huge influence, I think, on all of us here. So we do really miss him. You can see Bobby and I , so this was kind of the standard Lawrence, you know, Tuesday night, it's called LPDN, Lawrence Programmer's Drinking Night.

This is where the idea was conceived. All good things start at bars. And this is the only photographic evidence of the time of the three kind of creators who did this who are actually all in the room today. Bobby Grace, who is designer, and he's now kind of the head of design at Trello, which I use every day. And then Charlie Leafer, who's done Pee-Wee, and just a bunch of other just amazing, awesome Python stuff. It's just this really awesome three people sat together down, sat down for a weekend and just built it because it was a problem that we had. So from there, we kind of had this tool, right? And tools are great, but they're very specific and they're not they're not that important. They're just they just do something for you. And so over the next few years we kind of slowly grew and kind of the community started to kind of see that this was an interesting tool.

So these are kind of the weekly page views. So you can see in about 2013 we're up to about a million a week in terms of page views. So we had just a bunch of people using our tool, but we had no community. As Jacob said, we just had a bunch of users and no community. So we're like, how do you build community? You get a bunch of damn people in a room and you build community. You that's how you do it. And so we started Write the Docs as a conference. That was kind of the the user conference for Read the Docs. It was like yes, let's get all the people that care about this problem and and put them in a room. But then something that we kind of planned as kind of a 75-person little regional event up in Portland. Um we like announced it and it got on Hacker News and it was on like you know Reddit programming and it just kind of blew up and we're like, oh god. What have we done? Um it kind of turned into a 200-plus person conference the first year.

And really the interesting thing is that we threw a party for our friends and like a whole bunch of other people showed up we didn't know. But there were all they were amazing and awesome as well. So there was this whole community of kind of tech writers, support people, and programmers that kind of care about documentation. And they all came together in this really, really interesting way. And so that really helped me kind of like expand what I thought of as documentation from being like a tool that helps me accomplish programming tasks. To really being like a field of study and something that's really worth kind of thinking more deeply about. Because documentation is more than a tool. You know, it's a way to teach people understanding of Like a worldview.

You know, it empowers people to be good at their jobs. And it it's an entire skill set that's distinct from programming. I 'm sure all of you have tried to write books or blog posts or even you know emails and you're like, how words? Like it is it is a fundamentally different skill set that is really, really hard. And so the way that I've kind of been able to kind of boil this down in my own brain, you know, is programmers learn how kind of the mental model of code works for programmers. Designers think about, you know, how this will work for the user. Will it work well? But tech writers and people that have to kind of do documentation, they think about how they can teach understanding to users. So programmers think about the mental model for programmers, writers think about the mental model for users.

And that is like a fundamentally an important kind of difference. And it was something that was really kind of eye-opening to me because it's like, I'm so involved in the programming side, it's really hard to be empathetic to users while you do that. So this was really amazing. You know, we had this room of people that I was just learning so much from. And so now it's like, what do what do I do with that knowledge? And like how do you how do I process that? So I really started to kind of just like think about it at a high level. And so, at least you know, in my story, Django led the way. It was kind of the place that was doing documentation well and really kind of gave me the religion. And so with Read the Docs, we took kind of that Django and Python culture and we started exporting it. Kind of as Jacob said. You know, we started in the Python world, but at this point, um

read the docs is much larger than Python. Um we have like Julia, which is its own language, hosts its stocks on read the docs. We have lots of Go and JavaScript and all that kind of stuff. So over the last few years it's really started to kind of grow from there. So currently we get about 15 million page views a month from all sorts of different um language communities. I mentioned Microsoft earlier, so yeah, we're actually helping Microsoft open source all of their documentation. So like ASP. ,. NET, you know, you might have heard of these things. Um you can go to docs. asb. net and you'll be greeted with a very familiar read the docs interface. Um it's it's really just kind of magical being able to go into these communities. these other communities and be like, yes, this stuff is incredibly important and you should be doing it.

And we in the Python world have been doing this well for like 10 years. And now we're starting to really share that knowledge with the rest of the programming world. And they're like, oh wow. Like we finally came around to realizing that documentation was a problem that we had. And these Python people have been doing this for the last five years and it's like amazing and they have all these tools already built, um, which is really, really cool. So, kind of why does it matter that we have documentation? So, my favorite answer to this question. It's because you don't want a community full of people who don't read documentation. Think about what that means for a second. It's like I'm the guy who like There were no docs, but I powered through and I read the code and I'm like so damn smart and now you have to do that too.

That's like the rite of passage for being a contributor. There's projects like that that exist in the world. It's like I didn't have docs, so you don't get docs either, you know? Like, like who who wants to be a part of that community? And I've always felt that the Django community is a very special place. It's always been kind of my home. Um and I was just amazed when I came to Lawrence and serendipitously I was in the place with all the people that I loved and you know there's there's some element of I don't know who knows but I think a large part of the Django community being so amazing has been the documentation culture that's been around for so so long. So the other thing is if people don't read documentation, they don't value their own time. If they don't value their time, they sure as hell don't value your time.

So you just get this incredibly entitled user base that's like, it's just I I highly recommend if you're ever going to do any kind of project, have good documentation Because you'll get a whole different class of users who want to be helped. You know, like it just makes life easier for them. So this room of people has so so much knowledge. And that's I believe is our job going forward is to take that knowledge and share it with people. There's this whole thing in the programming world, right, about you know outreach and all this kind of of stuff. And we need to share our knowledge to help the people that are learning. And if we write really good documentation, it will make it so much easier for them to learn from us. And so this is what I've kind of learned over the years is documentation is actually outreach.

You know, there's all these coding schools where it's like, okay, you have three months, you have six months, and then you kind of You get out of that and then you hit this wall. And documentation is kind of the next like step on that path. If you are learning how to code and then you hit a project and there's no docs and you don't know how to do it, you get discouraged and you stop. And so there's kind of that middle ground where there's like the coding school infrastructure is really good, but we need to make sure that all of our software is documented and that we're able to kind of give these people an easy path into the profession. And so one of the things I kind of have to take Django to task for is internationalization. So we host the mirror of Django's documentation. So this is the only data that I could get.

But in the last 30 days, there have been Django users that have come to the Django. readthedoc. org site, which is you know 1% of the Django traffic From 66 different countries in the last 30 days. This is like maybe 0. 1% of the Django docs traffic. And only 60% of those users have English as their first as their preferred language. And the fact that Django doesn't have internationalized documentation is shutting off an entire kind of world of people. There are some unofficial like French translations and other things. But like you shouldn't have to learn English and programming at the same time. And I I totally agree with people that say, you know, it's like, yes, I know the references and that kind of stuff are incredibly hard. to uh to translate. But things like the tutorial and other things that are kind of like beginner level stuff that get people up to

up to speed. And the Django girls have done an amazing job with this. Um I didn't check exactly but I think there are tutorials translated in into like six or seven different languages. And that's huge. Like there's obviously a demand for that, and it's incredibly important for people that are learning to kind of being able to lower that barrier for them. And so kind of when I looked back on this whole story and I was trying to put this talk together, I was trying to think, you know. Like there's this very amazing narrative of me not being in Lawrence for five years and kind of my path into Lawrence being through documentation and my path kind of Going on, you know, being about documentation. But there's so many people in the world who are just starting down that path. They're just starting, they're going through the Django Docs for the first time. They're downloading that PDF.

You know, and there's there's so many other people in the world that are trying to learn this craft. And every piece of documentation that you write right, may help someone else along that path. It may help them learn to code. You know, it may help them get their first job. It may help them graduate college. It may lift them out of poverty, you know, who knows, but the power of documentation within our community is incredibly, incredibly important. And so this was kind of said best to me by someone last PyCon. And they said, I can't say that I'm self-taught. I've been taught by the people who wrote the documentation. Thank you.