Docs are not optional

Yeah.

What made you capture it so well? Because it was perfect.

Well, thank you. I think probably what made me capture it so well is that I’ve been working with a team of writers for the past couple of years, and they have taught me a lot about how to write. I noticed that my writing got a lot better and I became a much more of a stickler for good structure and documentation. And just like even in my Slack messages or my emails and things like that, the writers really rubbed off on me, and that was really nice, because being really detailed about writing is not my strong suit. That might sound kind of weird coming from somebody who led a documentation team, but I know that about myself; I actually leaned on the writing team pretty heavily to help me edit things and make things sound a lot better.

But I think for me, I’m really passionate about enabling any developer anywhere in the world to build and ship world-class software, regardless of where they are or what machine they’re on. And I think that unlocking that moment of like, “I have built something and now it works” is really, really important to me. Not only because – like, just for me, I remember that feeling of coding something really simple when I was getting into working on the web, and it just felt so cool; it felt so much like, “Oh my God, this is magical. I can create stuff.”

My family - I am from a family of musicians and artists, and I was the scientist. And I was always kind of like, “What I’m into is not what they’re into.” I’m into coding and mathematics, and I was actually really into a lot of like animal science and things like that. So I was very different.

So when I figured out like, how to make websites, it was kind of at this moment of like, “I feel like I, in a way, belong”, because I was making something that could be considered a work of art. I was never that good, but that moment of magic of making something and seeing it work was really important to me.

And I’ve been blocked before, and even on just simple things that are rudimentary, that I do all the time, that I don’t always remember what the syntax is or whatever, going to the documentation and having it very clearly laid out for me, was really important just to get me back to the business of coding, basically.

I think docs are very, very important, and I used to subscribe to the belief of like docs are a crutch to enable poor user experience, or things like that… And that definitely was a long, long time ago. But I believe that and I’ve definitely grown out of that thinking. I think docs are part of the product. And the more they become part of the product, the more they unlock that magical moment for people.

I think that’s really important, because as someone that writes code, gets out there and just has to answer, “Does it work? Does it do what I think it does? Does it address the problem that our users have?” That’s great, but to go beyond that; there’s so much more. And that’s almost like level one. Well, what about level 10? And there’s like all these layers, and I’m not sure exactly where docs fit, but it’s definitely part of the whole story. You can’t just be writing code and you can’t have just great automation on its own.

Yeah.

Docs play a very important role. And it doesn’t mean that your software or your system or whatever you have is not self-explanatory. It doesn’t mean that. The crutch - you’ve put it perfectly. It’s not that; it’s another layer, another perspective to your products, to what you build, to what you believe in. So how do you capture that?

I really strongly believe that docs are an API to the product, and we need to treat that – like, there are several different interfaces… There’s the SDK, there’s the web, there’s the application and then there’s documentation; it’s an interface for the code. And when you think about it that way, it really helps you connect the docs to the code in a way that is just going to empower more people to use your product. And that’s what you want.

At GitHub we saw a lot of our documentation was used by people who were very new to the platform. And that makes sense. I think a lot of documentation teams probably see similar kinds of traffic. And I think for those kinds of users, it’s like it’s on us to connect the dots for them, and make sure that they’re onboarding sufficiently and in a way where they don’t feel like they’re like, “Okay, well, I’m using this new thing.”

Take Vercel – I’m at Vercel right now. Take Vercel as an example. We could have people joining and signing up for Vercel all day long. But if they get frustrated and they can’t deploy their site, they’re probably not going to come back, and they’re probably going to go to one of our competitors. Now, that’s totally fine, because that means that, they’re getting their answers somewhere. And I would rather have them on the web than not on the web, not deploying their site. So I’m fine if they can’t figure it out with us and they go somewhere else. But I do want to know what their frustration was. And if it was documentation - that hurts, because that’s one of the places that we can easily update and we can easily help them through that experience, and I think it’s our obligation to do so. Because it is so simple. And we do get so many signups coming through. And it’s kind of like, when I was at GitHub, you’d see this kind of like, people sign up, and then some of them churn off of the platform. And I kind of have this belief that docs can be a part of helping them through and helping them stick around and helping them use GitHub in a really cool way. Not in a selfish way, but we want to obviously keep our users using our products, but I want to make sure that they’re using them to fulfill their dreams, and that’s where docs can really help them.

That makes a lot of sense to me. And I really get it. Through and through, for years, same page, definitely same page. But I’m wondering, for someone that is focused 80-90 percent to just shipping code, what would you tell to that person when it comes to the documentation

Yeah, so the one of the pieces of feedback I hear a lot is that developers don’t like to context-switch between working in their IDE or looking at – getting stuck looking at code, going back and forth to all these different tools, they’re working in the CLI, they might need to go to github.com or vercel.com for things… That can cause just a lot of churn, I think… And so when you’re spending a lot of your time in all of these different tools, you do you get a lot of that whiplash. And so I think where docs can help you and where we can take docs is creating systems that bring docs to where the developer is a lot more. And so one of the things – I don’t know, if I talked, I can’t remember if I talked about this in that article that you referenced in the beginning of the conversation, that maybe it’s time we re-think docs… But I do think that creating better API’s for documentation so that developers can bring that documentation into where they are, or either themselves, maybe they want to have access to the functionality in a certain way, because they’re building tutorials, or they need access to the documentation, where they are in the IDE, things like that - I think we can do a much better job at bringing the content and bringing the docs to where you are, even in line as you’re working with a CLI, for example. And so I think a lot of documentation, especially for developer tools, is very, very web-focused, and I think it can we can really start to think of it as a system that can work with the developer toolset in the workflow, as they’re going through developing, looking at staging etc. and then actually deploying it.

I think that makes a lot of sense. And I’m almost wondering, if someone that really cares about code, shipping good code - would tests be optional? I think the answer is no for the majority. What about actually getting the code out in production? Is that optional?

I would like to think that for most of our listeners it’s not, right? You want to see your code in production, you want to understand the behavior at production scales, so on and so forth. So the natural question is, why are docs optional? Why do you think they’re optional? So why do you think docs aren’t optional?

Well, I think they’re not… Yeah.

Yeah.

There’s a little bit of philosophy here, and I think it probably depends on – the answer probably depends on who you talk to. But my philosophy is that the product doesn’t exist until it’s documented. And the reason for that, and I think you can probably connect the dots, is that I really feel that documentation is part of the product itself. And if you don’t have documentation for people to get their answers, or for people to give you additional feedback about how they may be interacting with the docs, or with the product itself, then I think you’ve kind of failed.

But I do think that the reason why a lot of people, maybe people don’t think docs are optional, or maybe they haven’t thought about this question to the extent that I think would really benefit them if they do deep-dive into this, is that a lot of times you’re up against a timeline and you want to get stuff out. And docs typically falls after you have finished a feature or finished a part of the product… And then you’re up against “We’ve got to ship this today”, and docs often just gets cut from the launch plan. And I think that’s unfortunate, because there are so many opportunities… If you think about docs as code and you start to structure how you work with documentation, you can actually document things really easily along the way. And especially if you’re working really closely with writers and developers who – at GitHub, we always talked about the EPD, the Engineering, Product and Design team. And right before I left, we recently started talking about the WEPD, the Writers Engineering and Design team, and bucketing them all in one, because really, the writers can help a lot with end user testing, they can help with feedback, they can help you make sure that your entire feature actually makes sense for the end user.

If you think about writers almost as designers, but at the end of your iteration, they can really help you improve a lot of those details over time. And if you do that, then you’re constantly kind of writing documentation alongside, as the software is being developed, and iterating on that documentation to make it better and better and better, because you’re treating it as part of the product within the same system that you’re developing. And I think that’s probably not something that a lot of teams – if you’re lucky enough to have a team of writers and think about documentation, then oftentimes you’re thinking about it at the end of the cycle, and then it is at risk to get cut before it goes out.

I think that’s exactly right. And that’s how [unintelligible 00:14:37.22] even started, when you said that we need to bring the docs closer to where the code writing happens. And having writers involved with that process is one way, but what happens when you have a smaller team where you have, I won’t say like a one-person company, but let’s say a five-person company, where you don’t have a dedicated writer. What would you recommend in that case of that team does?

Yeah, I mean – we’re in this situation right now at Vercel, we’re hiring technical writers, but we don’t have any on staff. We have documentation, we have great documentation for Next.js and Vercel. How did that happen?

So I think that the people who know the most about a product are the people who are building it. And the benefit of this kind of situation is that you can get those people to write the documentation. And that’s often what happens, but you kind of have to have this ethic that I talked about, which is like documentation can never be an afterthought; you have to think about it as you’re building, and also celebrated throughout. So that’s been my experience so far at Vercel.

And when I was at Heroku, we were in the same situation. We had documentation, but we didn’t have writers. And the product team – a lot of people would say it falls on the product’s team shoulders to write the documentation, or it falls on the engineers’ shoulders. I think it’s an opportunity to express what you have built, and also take a step back and almost go into the same mindset that you had when you were writing the spec, when you were approaching the problem. Now you’re at the end of the problem and you’re about to ship it; you can go into that same mindset of like, “Let’s review and make sure that what I’ve built actually matches what I intended.” And that what this writing process can help you with.

That said, we do have people in both situations at Vercel and at Heroku, we do have people thinking about the documentation system and thinking about how to write good articles, and providing that information to the rest of the team in a form of a system - system notes, system documents etc. So that when you do go to – if you’re not a writer like me, when you do go to write documentation, you have the resources you need, to know like, “Okay, well here’s how the system works. Here’s how the taxonomy works.” There’s somebody kind of thinking about that. And sometimes that falls to a product manager or somebody who’s doesn’t have a documentation background. And I think that’s awesome. I think having people thinking about the system in terms of the way that it’s designed, who are outside of our writing discipline, is really great, because they’re thinking about the product of the docs itself, and I think that that really helps.

I think that makes a lot of sense.

If you don’t have any of those people, have a champion.

Yes, have a champion. Okay, so someone that reminds you of the importance… Someone like you, right? Hey, docs is important. This is why it’s important. This is what that looks like, so on and so forth.

Yeah.

So that makes a lot of sense. Product people helping with the documentation, if you don’t have writers. It helps to have writers for the taxonomy, for the structure, for like the higher-level concepts that are specific to writing, what makes good writing, which is very important… And you mentioned how much it changed your outlook on good documentation having worked with good writers, so that is important.

But what about – I’m just a developer, okay? I have to write my code, write my tests, preferably first, commit, push, get it out there, get it in production.” At what point should I, the developer, write the docs?

You hit on a good point, which is – I don’t want to underestimate the work that it takes to write good docs. I think technical writers are – and this may be controversial to say, but I think they’re undervalued in the industry. I think especially technical writers, for very technical tools, for developer tools, for the space that I tend to work in, we demand a lot from our writers, and what happens is they’re undervalued, so they’re overstretched. So we only hire like one or two of them to document an entire product. And that means that where you might hire one or two technical writers, you have five or six product managers who are shipping things, a team of 100 engineers who are shipping things… So those two technical writers then have to know everything about the system, whether it’s existing legacy, or new and upcoming; and that’s a lot of demand on them to not only understand what a technical writing system looks like, but also really fully understand what the product is.

So when you find these people who work on these small teams like this, they’re brilliant and they can do a ton of things; not just writing, but most of the time, they want to do writing, because that’s what they’ve chosen to do for their profession. So I definitely don’t want to undervalue them and say that their job can be done by somebody who’s not a technical writer.

But I think if you don’t have a technical writer on your team, you can do things like document as you’re going, and that’s kind of what I was talking about before, where it’s like, treat documentation and writing as part of your development process. You know, that introduces another step in a lot of ways, and something that you can forget about, but it helps you in the end, especially looking back… Like, okay, you now have a record of the decisions you’ve made and how things have changed, and that can help your development process in the long run.

So the way I understand, there are about three stages. The first stage, the incipient one, is docs don’t exist. Now, that’s stage zero, and that’s a bad one to be. That’s maybe the worst one to be in, just ignore docs altogether.

Yeah.

The first stage, the first proper stage is to write some docs the best you can as a developer, as you build a feature. Don’t leave them last, because you’ll forget; think about the user. If anything, it forces you to think about the end user more as you write the docs. How will they be consuming this? What problems might they have? …so on and so forth.

Then, as a product team, encourage the product team to help writing the docs, because they have a higher level of perspective, a deeper, longer, wider, however you want to take it - just a larger point of view into how this feature fits in the product, and that helps. But what you should really be doing - and this is like level three, or the last one - have some technical writer; have this team, the cross-functional team, which includes a technical writer, which is super important, and maybe is no longer optional, because our products are growing more complex, things are changing faster, and you forget the human element. You think it’s just like about slinging code, just get it done. It breaks. “Okay, we’ll fix it. Let’s move on.” Well, maybe what you should be doing is maybe slowing down and investing in good documentation.

Yeah, definitely. You know, you mentioned the human aspect of it, and I think that’s really important. One of the things that I talked about in that article is writing documentation that can be flexible for how people learn; people learn in many different ways. I am a very visual person, and so I like to pair a lot with people, I like to see their screens, and I like to see and watch other people doing things. So videos really help me learn. And other people like to get hands-on, and that really helps them learn.

Some people, and I envy them, but just reading helps them learn. And so I think it’s really important, if you can, think about documentation in a way that meets people’s needs, and helps them learn in different ways. And one of the things that we started to look into at GitHub was - you know, just take the simple article template, and say we’re looking at a guide or a tutorial. That guide can be presented on one page in three different ways. You can have the text on the page for those people who read through it, you can have an interactive element, where people can play around with the code. You could actually manipulate that code and take it with you if you needed to. That can be really powerful too, because then you’re merging the learning and the development in one place, and you have that context in your head as you approach your project.

And then you can also - maybe in the same place where you have the interactive element, you have a toggle between interactive or video. And then if you’re watching a video, have it be somebody just literally showing their screen, walking through the steps of that article, because the point isn’t necessarily to talk about something else or introduce other ideas. The point is to learn what’s on the page, and that can be very valuable. And if you do have a team that can introduce content in various different ways, I think it’ll pay dividends to your goals for signup churn or for engaged users and things like that.

This is exactly what I was thinking about hearing you talk about documentation itself - most think it is just text; walls and walls of text, man pages. They have their place, but that’s not the type of documentation that we are thinking about. And that’s actually the second thing, which I really loved about that post, which is maybe it’s time to re-think docs. I’m going to link to it in the show notes… Where documentation is not just text - it’s videos, it’s the interactive elements. Because documentation - and these are your words, Kathy, and I love them - they’re learning experiences. That’s what it is. You’re trying to learn something; you don’t understand something, you’re blocked. And that blocked means you’re missing a piece or maybe multiple pieces. So how do we get those pieces? Reading text - most people are fine with that. But I think we’re seeing – I don’t want to say like a new age of developers of like a new trend, but I think in today’s age, video, I don’t think it’s optional anymore. I think it’s something that people expect to have. Also the interactive element - super-important. So if you stop thinking about docs as text, but more as learning experiences, then you start realizing, “Well, hang on, do you mean all my demos and all my pitches, and all my things are actually docs?” In a way, they are. “Are my blog posts, docs?” In a way, they are.

I mean, sure, you can do that at the end. I know that Amazon, with starting – what was the name of the book? Hang on, let me just pick it up. Working Backwards. I forgot about it, there’s just too many books. Working Backwards. That’s a great way to start with a feature. Imagine it finished, imagine it in front of users, imagine the press release. Maybe that is the final doc that you create, and then you just work backwards from that, maybe.

So I really like this about your article Kathy, where you, first of all, give an example of what GitHub docs look like in certain sections, and you give an example of what they should look like. I love that; it’s so clear, even in the example itself. How did you come up with the idea?

The idea to introduce interactive elements?

Yes, interactive elements to expand people’s horizons, that “Hey, it’s not just text, it’s actually videos. It’s actually interactive elements.”

Yeah.

Just open people’s eyes to re-thinking docs, literally. That’s the essence in my mind of that blog post.

Totally. So when I was at Heroku, there was a rule that we were never allowed to put any marketing into our documentation. And I really subscribed to that; like, yes, don’t put marketing, don’t get in a developer’s way with trying to sell them things. And I think a lot of people take that to heart and they think like, “Okay, well marketing means slide decks and demos and videos and things that actually make a page come to life.” And so in order to not have marketing in your page, you have to make it really dull. And that really sucks for people like me, who learned in different kinds of ways.

And so I was just thinking - you know, I constantly want to revisit, “Was this a good idea?” Just because we’re doing it, it doesn’t mean that we should be doing it. And you kind of fall into this trap of like, “Oh, well this is the way that it’s been done forever.” And so I really like to question that, question my own thinking, and question my team’s thinking a lot, of like, “Well, just because that’s the answer doesn’t mean it’s the right one.”

So I kind of took a step back and said, “Well, what if we introduce – what if we talk about the value of what GitHub Actions is and introduce just a little bit of marketing?” And I realized, it wasn’t marketing that I was introducing, I was introducing a story. And we should be able to tell the story of this feature, of this product, and who it’s for, and why you might use it on your project in the documentation; not just this one to one “Here is the feature, here’s the UI” or “Here’s the CLI component” or whatever. And then just like have that one to one, UI-to-text document. We should show people using it. And then I just got thinking like, “Okay, well, what if we add a video?”

I looked around – as a product manager, I looked around and did a bunch of competitive research. I saw that Netlify was adding videos. Why can’t we add videos? CircleCI is adding tutorials that are not written by anybody on their team, they’re written by the community. Why can’t we have that in our documentation?

So it’s kind of this FOMO moment, of like, “Well, other people have this thing. I want this thing.” And then I started to put it together… You can actually incorporate all of these elements into one screen, if you think about it like a system. And then it can start to help that product or that feature really come to life for people. And then you go through – like, I went through my typical product development process, which is like sketch something out, show it to somebody, get some feedback and then go a little bit further.

But what’s really interesting is – you mentioned something that I really like, which is you’re new to this project, you’re new to a product, you want to test it out, and documentation is really important for people who are kind of new to something… I think that’s very, very true, and in a lot of ways, I structured – I didn’t talk about this in the article, but in a lot of ways, I structured the way the pages were laid out based on our most trafficked user, which was the person who is new to the screen. I wanted to prioritize their use case.

That said, we get a lot of – at GitHub, we got a lot of traffic from people who are not new to GitHub, but were new to the documentation in certain ways, where they were like using GitHub for very predictable things… But then when GitHub Universe happened and we introduced a brand new feature, everybody would get really excited about it and turn to the documentation right away to go learn about it. And so those folks we definitely want to cater to as well. So it’s kind of like, you’ve been here for a while, we’ve just introduced a new feature, and so we want to be a little bit splashy with it. So we want to introduce some cool things.

I mentioned GitHub Actions… One of the things we did was we revamped the GitHub Actions page to where we weren’t just documenting like a one to one, like I said, “Here’s the UI. Here’s the UI in text form.” We were starting to incorporate a lot more of the community.

So GitHub Actions - one of the coolest things about it is that the community writes these Actions and workflows. And they sometimes are hard to find… Especially if you’re just getting started with GitHub Actions, you have to kind of like troll through a bunch of repositories, and go in and read somebody else’s – we could talk about repository documentation too, but go and read their documentation about what this thing does… So the discoverability was hard.

So what we did was we actually built a component within the GitHub Actions page that pulled some of that information into the GitHub Actions documentation itself, and it allows you to search different code examples for how to use GitHub Actions. And I think that unlocked a lot of the a-ha for people, because they were like, “Oh, well, GitHub Actions - I can go and try it right now.”

That component was really easy to put together. It was literally like, we added some frontend code, and then it was me updating a YAML file with – like, manually updating the YAML file with links to all of these repositories. I think I wrote a bunch of the description text myself, just to get it out there and see if people were using it, and they loved it. So there was just this kind of like – you went from having FOMO to participating in the FOMO. That’s what the documentation unlocked.

And the final thing I’ll say about this is wanting people to have that magic moment, and then seeing them have it is super-gratifying for anyone who is building a product. That was really fun, and that was very motivating for me to keep going.

This makes a lot of sense in my head now. So I remember using GitHub Actions when it first came out… And I remember a lot of things being primordial, and just a lot of questions not being answered. And over time, it got better and better and better, to the point that I like it really much. I mean, at this point, I’ve tested all the CI’s that there have been in the last 15, all the popular ones, by far. So anything that you have used as a listener, I have tried out myself, and even used myself. And I can say that GitHub Actions as a product was brilliant, and it continues being brilliant. Documentation plays a big part in it. It’s still YAML, and there’s still that dissonance between, “Well, what do I put in this file?” And then you go to the docs and you have all the reference, and “Okay, so what do I actually want?” You have some examples to get you started. It’s okay, it gets you there, but then it keeps hand-holding you through the entire process. And you can build some pretty good pipelines with GitHub Actions, just by following the docs.

You look at some examples, more advanced ones, all the different GitHub Actions you get from the marketplace, they also help and they have their own documentation, so that’s good as well. The marketplace makes a big difference, but overall, it’s a nice experience. And even though GitHub Actions itself, it has various limitations… As everything, by the way. Nothing’s perfect, stop looking for it, it doesn’t exist, by the way. It’s really, really good, and I liked it.

And as a whole, it felt more human than any of the other CI systems that I used. And as I said, I went through many of them; look at the show notes, I’ll drop a few, the most popular ones. But there’s something to be said about the product. There’s something to be said about the experience, whether it’s a learning one, or using one, it doesn’t matter where you stand. That experience is really important. And documentation - it contributes to that. You can’t have –

It really helps.

…a good product experience without good documentation.

I think what you’re getting at is – there’s kind of like two things. Documentation is a detail that you should not overlook. When we first released GitHub Actions - this is a little bit of inside baseball, but when we first released GitHub Actions, and I think a lot of people who release a big product will empathize with this… It was definitely awesome, and it was like “Oh, my gosh, this is going to change a lot of workflows.” And it connects a lot of workflows right inside of GitHub, so that was super powerful. But, it wasn’t perfect. Not that we were seeking perfection, but it needed some improvements. And one of the things the team did was they took a couple of the iterations and they said, “Okay, what details matter here? What should we focus on?” And so they shipped the thing, and then they revisited it again, and again and again. And so even in the UI, like – and they also pulled the documentation into the UI, which I love, but they perfected those details over time. And I think what you’re saying is a reflection of that hard work that went into that.

Yes.

And I think even the documentation - we released the initial documentation for GitHub Actions, and it was okay, but we needed, especially as the product evolved, we needed to iterate and keep up. And when I first started on the team, improving the documentation at GitHub as a whole was a big mandate of mine… But I picked a white whale, which was GitHub Actions, because we had been getting a ton of feedback about the GitHub Actions documentation specifically. So I said, “Well, if I’m going to do it, I’m going to jump into the deep end and I’m going to go after what we get the most amount of feedback from.”

And one of the things I learned in that experience was that it is really powerful seeing how other people do things. And not only for myself, but for other people. It’s like, you go to Stack Overflow and you ask for an example, you’re seeing how somebody else might solve your problem, and it’s the same thing that we wanted to apply, bringing these code examples into documentation. It’s like, how are other people working with GitHub Actions? How are they building their workflows and their pipelines? What are the other examples that I could then apply to what I’m doing? There’s a lot of power in that kind of thing. It goes beyond a template. It is actually how somebody is using it; that can be really eye-opening.

The one thing which I really liked about GitHub Actions is seeing how it changed week by week, month by month, and it’s that journey that I was on by using GitHub Actions that felt comfortable. I knew that the shortcomings which it had will be addressed. I knew that the frustrations, the small ones, with the documentation, with whatever it may be, eventually will be addressed. You had a very good GitHub community where I could ask questions, people could join, and it felt like it’s part of the GitHub experience, of the GitHub Actions experience specifically. And that really helped. The marketplace kept growing, people kept building more awesome stuff… So it wasn’t just GitHub, it was the whole GitHub Actions community contributing. And that felt great. Seeing things improve constantly, at a comfortable pace, the trust element growing - it was amazing. I really liked, and I still like and enjoy being part of that journey. How much did you have to do with that, Kathy?

How much did I have to do with that?

Yes.

Specifically on the GitHub Action side… So I was not on the GitHub Actions’ team. I worked closely with them, in that my direct colleagues are running that team. But one of the things that – I can talk about it from a documentation standpoint, if that’s what you mean…

Yes.

But one of the things that you’re touching on, which I think is really, really important, is that when you started using GitHub Actions, it was a product that was in beta, basically. We had just shipped it, and there were some things that we needed to improve, and the team was really interested in collecting a bunch of feedback, so that we could improve those things.

At that moment, you are taking a huge leap of trust, because you’re talking about putting a lot of probably your critical developer workflow infrastructure onto GitHub Actions. And in order to use CI/CD, and to use that integration is really, really important for the success of your products long-term. So you’re trusting GitHub to update the product in a way that it’s going to work for you; that’s a ton of trust. So I take, a couple steps back, and I’m thinking like “Okay, why did you do that? Why did you make that decision to trust GitHub in that way?” And I think that trust is earned.

And if we go back a couple years before, or like a year before I joined, GitHub had lost a lot of that trust with users. And I think very famously with the Dear GitHub letter. So the Dear GitHub letter, if people don’t know what that is - it was a letter that was from the community, asking for certain features and certain products to be updated in a way that could really, really help maintainers. And maintainers are a big part of GitHub, maintainers of open source projects. So there were a lot of kind of like low-hanging fruit things, there were a lot of bigger projects that people were asking for.

And so kind of in response to that, in response to losing the trust of some of our maintainers and some of our users, we decided to put together a project that I called [unintelligible 00:42:02.18] And we talked about this publicly, we talked about this – we can link to it in the show notes… We talked about this in the Dear GitHub letter; it exists in a GitHub repository, so you can go in and see openly what the conversation is around all of this stuff.

But we decided to take some of those requests and rapidly iterate on them, rapidly iterate on our platform, to not only win the trust back of some folks who we consider very near and dear to the heart of GitHub and in the DNA of GitHub, but also to focus on the details, because the details are what matter for developers. And if you don’t focus on the details, those are things that add up and end up getting in your way and end up really kind of a trickling stream into a raging gorge that you can’t cross.

That’s right.

And we wanted to fix these small details. And over time, they add up to a huge win for our community and for these maintainers, and they paid off in dividends. And one of those dividends is trust. And so when you come to GitHub Actions for the first time and you’re thinking, “I’m going to now put a critical piece of my workflow onto this new in-beta, just-shipped product”, you can trust that GitHub is going to focus on those details over time, and that’s exactly what we did.

And the GitHub Actions team shipped this thing, and then they said “Okay, well, there are certain parts of it that aren’t perfect.” And we are, like – you’re always striving for perfection, you’re never going to hit it, and so it’s good motivation to keep on fixing things as you go.

And on the documentation side, we felt the same thing. We shipped the first set of documentation for GitHub Actions, and it wasn’t great. We got a lot of feedback about it very publicly, about how we could improve GitHub Actions.

And so when I started on the documentation team, I just kind of said “Well, one of the biggest frustrations from our community that I can see publicly and in the feedback we’re getting just directly to the team is that the GitHub Actions documentation can be improved.” So I picked that as my first thing to focus on when I was re-imagining how documentation could look at GitHub.

And some of the things I learned right away was that people had a hard time finding examples in the wild of what other people are doing, and they wanted to see that in order to – there’s a little bit of like “Let me see what other people doing so I can help contextualize it for myself.” And then there’s a little bit of like, “Let me see what other people are doing so I can trust that system more.” You know, get proof that this works for other people. And so we wanted to incorporate that a little bit.

Also, at the time that we started revamping a lot of these docs, we introduced a new documentation type tutorial into our system, which exists in a lot of different documentation systems… But we spent a lot of time thinking about and working with a team of technical writers, about 20 of them, who were working across GitHub, but a couple of them who were working specifically on GitHub Actions… But we embedded those technical writers on the GitHub Actions team, to work with the engineers and designers on these tutorials, so that we could kind of like get closer to the metal, I guess, and ship tutorials that made a lot more sense than they did in the past.

The thing which I’m thinking about now is writing documentation and getting documentation out there, part of the same repository. I know that a lot of what we talked about is bigger teams, larger organizations… But if you’re a smaller team - again, just a handful of engineers - and you’re trying to ship stuff and do everything else that you do, as you would expect when you’re part of a small team, would you recommend to have a single repository and put all your documentation there? Or would you recommend focusing on the code first, on how everything behaves, and then having documentation separately to your code? What do you think?

I mean, I think it depends on how you work. I think if it’s useful for you to have it separate, then do that. If it’s useful for you to have it in the code itself, then do that. I think, if you’re just starting out, you’re probably going to private beta or like ship something in public, but ask for a lot of feedback… And so it can be really helpful at that time to have the documentation in mind with the code.

The way that I would think about it, and this is one thing that I do when I’m just starting a new project, is that I think about my documentation like I would release notes. And when I get to the end of my day or whatever, I’m kind of thinking about like “Okay, what does this release look like for people? What are the bullet points that I really want to highlight?” And I just start there, and then that helps me; I can fill in the gaps later on, but at least I have the skeleton. If I think about it in terms of like, how are people going to be consuming this once I released this package, or something like that.

The reason why I ask this is because I can see a lot of things coming together in a single GitHub repository, and I think that in itself is a very powerful concept. Not only you have code, you have the readme, you have GitHub Actions in the same context… Though you don’t leave your repository; it’s just another tab. You have discussions, which I love to see… And there was also the wiki concept for many, many years, but I don’t think that’s quite worked as well as it could have. It was okay, but I don’t think it brought the concept of documentation close to where the work was happening. I know that there’s also the project concept, and I think that’s slightly separate, but then you have issues in PRs, which are kind of linked with the project.

Yes, issues in PRs.

I mean that’s what a project is, right? All the items that you’re doing are the issues and the PRs. So I’m wondering, in your opinion, Kathy, what would a better documentation implementation look like in the context of a GitHub repository, alongside all the other things which I just mentioned?

We often talked about whether we should have introduced a docs’ tab in the repository, and it would kind of take – you know, like you mentioned, the wiki, and this is kind of what a wiki is supposed to be… But I think the word wiki is a little overloaded, and the wiki product didn’t take off, I think, in the way that it could have for – the teams that I talked to, that are using wikis, it really, really works. But you kind of have to make a commitment to – wikis can be kind of messy, and they’re intended to be kind of messy… Whereas documentation is something that you’re making a commitment to it being part of the product for the end user. And while you’re updating it, you’re constantly thinking about, like what I said, you’re thinking about, like “What if the release notes look like this? And how do I want my users, once I open this up, to consume it?” And wikis can be a little bit more organic… And that’s just my opinion. I’m sure what I’m saying is possibly controversial with some people who really, really love wikis. I used to love them; I don’t really use them that often anymore.

But I think there’s something really powerful about having the documentation right there with the code, in the repository, especially like – the documentation I was working with was documentation that was external, and also accessible without a login or anything, so external to the product. And so you almost have like the product up on one screen and the documentation up on another screen while you’re using it, and that’s like product documentation.

But what we’re kind of talking about now is repository or code documentation, and having that all in one place is really, really useful.

Having the readme document where you have installation information, and you have update information, and how to navigate this repository - all of that’s really, really powerful, and that’s a piece of documentation. And so introducing something similar to where you could potentially have the documentation or a docs tab is really cool, because you can also then tie that into how people are pushing code to the repository. And so you could say in every single pull request, or you have a PR template, or you have an issue template - you could have a portion of that write directly to the docs tab, documents in that tab if you wanted to. You could use GitHub Actions to pull that content in if you wanted to.

So there’s something really powerful about that kind of a workflow, where not only are you getting the context of having the docs in a tab for the end user, but you’re also thinking about the published flow, and automating that published flow in kind of a cool way. And we’ve been talking a lot about like – if you’re one developer on the team, you don’t have writers, this kind of a workflow could actually help you. It’s something we talked about a lot on the documentation team, like how do we go beyond just product documentation and think about improving code documentation?

I’m a big fan of everybody meeting in a single place and then seeing what happens, and a GitHub repository - to me, that’s what it is. The discussions are happening there, the automation is happening there via GitHub Actions, the code is definitely happening there, your issues, your pull requests, community contributions are happening there… The docs, I think, should happen there, too. GitHub Pages - it works; it works for you well. The wiki - sure. The wiki was a really weird one, because it was a repo inside a repo, and I don’t think many people knew that.

Yes.

You could just clone the wiki, and then you would have a repository of your wiki. And that was a bit like, “What?!” That was just a bit awkward. but again, it worked. And people that knew it, loved it, and used it, and so on and so forth.

Once you start having many repositories, unless you need them – and if you’re like thousands and thousands of people, you definitely need them. Well, I don’t know… Facebook, single repo; Google, single repo. I mean, maybe, I don’t know. I think there are extremes, but let’s not get bogged down in this.

You know, it’s really interesting… One of the things that we had to solve for when we open source documentation, speaking of “Do I have one repo or do I have multiple ones?” is that we had to actually – because we were the documentation team, we were documenting products that were under development, and so sometimes, we could do that out in the open, because the community knew about those things that we were working on, but sometimes we wanted to keep it a secret. And GitHub wants to make a big splash or a big launch, or we’re not ready to accept feedback or whatever. And so we had to document those things in private. But we had an open source documentation project going on, and so we actually created two different repositories for documentation. One was internal and one was external. And we used GitHub Actions to bi-directionally sync the two every 15 minutes, and we would actually only sync the PRs merged to the main branch. Everything else was different on both sides, but the code was a mirror, which was pretty cool. I thought it was a nice workaround for us.

Okay. Okay. Are those GitHub Actions public, by any chance?

Yes, the one that we used - it’s called Repo Sync, and that’s an open source project.

I’ll check it out, because that sounds really interesting. That sounds really interesting.

Yes.

We’re approaching the end of this… I know that some people, some listeners may be confused. The reason why they’re confused is because when I started talking to Kathy, she was at GitHub; but when we recorded - she’s at Vercel now. So I think that the only logical next step is to do another interview with Kathy from Vercel, because this one sounds a lot like Kathy from GitHub, right?

[laughs] Yes.

That’s, at least, what I think. So –

Yes, we can totally do that.

Yes, one focused on Vercel and the amazing work that you do there, and the amazing work that the team does, I think would be well deserved. Let’s put a pin in it for now. We didn’t even talk about Kathy’s philosophy page, kathy.pm/philosophy, that’s a great one. You have to check it out right now. Put on pause, go and check it out; it’s so good. I was going to ask you about your three favorite items from that page, but I think – I mean, if you have a quick answer, we can do that…

My three favorite… Well, I’ve just added one that I think – maybe I’ll just add my one favorite.

Okay. Yes.

It’s at the very, very top, I just added it. It’s about embracing failure, and I think that’s really, really important. I think a lot of people in this industry, myself included, have a lot of imposter syndrome. I have a ton right now, because I just started at Vercel, and I’m working with very, very smart people, and I have a job that is – it’s the biggest job I’ve ever done. So I think the way that I combat kind of imposter syndrome is to embrace failure as much as I can. And if I do that, then I’m constantly thinking like a scientist, because I’m trying to prove myself wrong in order to ship the right thing for the customer. And learning that was huge, because it gave me this huge out for failure.

This is exactly what I’ve been talking to someone, I can’t remember their name, two days ago. And I was talking to someone else, I think it was Patrick, two weeks ago, about learning from failure. Brian Lyle, I remembered him.

I was not talking, replying to a tweet; let me be specific and clear. I was replying to a tweet saying about how much more we learned from failure than from success. And my opinion is that it has to do with the bias for loss. People feel losing a lot harsher than when they win. They have stronger emotions about loss than success. And I think when you feel that you’ve failed, it has stronger emotions and stronger reactions within you. And it feels like a more meaningful experience, but it doesn’t need to be a negative one, by the way. I mean, okay, it depends on the type of failure. I don’t want to like go down the rabbit hole.

But if your experiment failed, you’ve learned something. And if you learn from failure - well, is there a better thing? I don’t know what you could learn better or what source of learnings is better than failure. And if you start looking at it like that, the world is your oyster.

Yes, totally. I mean, the fastest way to being right is to admit that you were wrong.

Exactly.

For me, it helped. It helped me embrace this fear of failure. I think it’s something that you have to embrace and use to help you just get better.

Yes. I would ask you, if a listener had to remember one thing from this conversation, what would that be? But from my perspective, it would be just what we discussed, learning from failure. Is there something else that as a listener I should take away from this other than that, which I think is the top one, the top item?

You know, I think that because we were talking about documentation, probably one of the biggest things I would take away from this conversation is that if you are shipping things specifically for developers, documentation is going to unlock that magic moment for them, no matter what. And that’s why documentation matters the most, is helping people get to that, “A-ha! Oh my God, I got it. And it works. And I don’t have to sit here and bang my head against the wall anymore, because I learned from the docs.” That feeling is so gratifying.

That sums it up so nicely, there’s nothing more to add. Kathy, this has been a pleasure. Thank you very much.

Yes, thank you for having me. This has been really fun.