GitHub GitHub Checkout, 10 Nov 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: Open Sourcing GitHub Docs - GitHub Checkout

Description

Show Notes
Open sourcing a project is never easy. In this video, Kath Korovec tells us about the journey GitHub went on while working to open source our own documentation, and shows us how anyone can easily contribute to GitHub docs today.

10:35 - demo: contributing to GitHub docs

Blog - How we open sourced docs.github.com
https://github.blog/2020-10-14-how-we-open-sourced-docs-github-com/

Blog - GitHub docs are now open source
https://github.blog/2020-10-07-github-docs-are-now-open-source/

Contributing to GitHub docs
https://github.com/github/docs/blob/main/CONTRIBUTING.md

Kath Korovec:
GitHub - https://github.com/simpsoka
Twitter - https://twitter.com/simpsoka

Sasha Rosenbaum:
GitHub - https://github.com/DivineOps
Twitter - https://twitter.com/DivineOps

End of show notes

Channel(s)
YouTube
Video
https://drive.google.com/file/d/1CH3SFQClODYS7wFtqZB8iY-En4XC0Xu7/view?usp=sharing

Sprout categorization/tagging:
#GitHubCheckout

Publishing Date
This week

Stakeholders
👀 @simpsoka

As always, feel free to leave us a comment below and don't forget to subscribe: http://bit.ly/subgithub

Thanks!

Connect with us.
Facebook: http://fb.com/github
Twitter: http://twitter.com/github
LinkedIn: http://linkedin.com/company/github

About GitHub
GitHub is the best place to share code with friends, co-workers, classmates, and complete strangers. Millions of people use GitHub to build amazing things together. For more info, go to http://github.com

A

Hello and welcome to github checkout, I'm sasha rosenbaum a program manager at github and my guest today is kath corvitz kat. Would you like to introduce yourself yeah absolutely.

B

So hi my name is kath and I'm on the product team at github and I've been at github for a couple of different a couple years. So I've worked on a lot of different stuff and I'm working on github documentation right now,.

A

Awesome and so logically, our our theme today is our recent journey to open sourcing github docs. What was the journey to open sourcing, the docs that you had to go through it.

B

Was a long one so about two years ago, two and a half years ago we started thinking about open sourcing, github docs, and so it's been a journey since then, and um there have been lots of different challenges along the way. But when you're thinking about something like this, like our docs set, is really massive. We document everything for all of our github products and we also have some documentation for things outside of the github ecosystem or github products, and so things like atom and electron are documented in there.

B

So it's pretty big so when you think about open sourcing, all of that there's just a lot of planning that goes into it, and so we started that journey uh yeah two years ago. Thinking about how we're going to do this, and then we got to about uh june or july and we're kind of like okay, we're um we need to.

B

We need to buckle down and actually do this if we're going to, and so uh we said you know what maybe what we should do is open source in october and maybe try to hit you know. Maybe we can get um into being an open source project for hacktoberfest, and so we gave ourselves that mandate, which forced us to think about all of the different tactical things that need to go into open sourcing, the docs um and there's a lot of different things that go into it.

B

Just for us, because we have this, we have, you know like we have our own special way to work with documentation, but we had to think about all of the community building tools that we needed. So our. What do? What do our contributions? Look like? uh We also um we internationalized and localized everything, so we had to think through kind of like what does that story look like for accepting localization contributions, um and then we built uh three different pathways to be able to contribute to docs, because it can be stuff.

B

That's very simple: you can find like a bug fix um like a typo or something and contribute, or you can go all the way to contributing your own article or your own github docs guide.

B

So we wanted to make sure that we were kind of covering all our bases, and so we took a long time to think through all of that stuff and then in june we kind of hit the road and started working on it and launched in october.

A

Wow, that's awesome, so the deadline really worked here. Yes, yeah.

B

It did it, it worked to also kind of constrain us. We were thinking really broadly. We wanted to solve every single problem for every single contributor, and so it kind of forced us to think about like okay. Well, what are the? What are the things that we can think about right now, and then we can think about scaling things later on, like, for example, we um the pathway for creating your own articles and your own guides, there's a lot of collaboration that goes into that with working with our content, our technical writing team.

B

We have a writing team about 15 people who will pair and and work with you on pr's for everything that you do on docs, and so, if you're, creating your own article, that session is a little bit more high touch, and so we want to put some real thinking into that. That's something that we are is in a private beta right now, so we do accept contributions from some maintainers and developers, but it's not open to everybody, but it will be soon so we're phasing things.

A

I think that's probably the best way to approach open sourcing any product at all right because you don't want to get overwhelmed. I know that at some point we were worried about being overwhelmed with potential contributions. Is that something that happened or is that totally was uh not a worry that came true not at all.

B

I mean we, we want to think about every kind of aspect and the reason why we worried about this- and we thought really hard about potentially becoming overwhelmed, is because we didn't want to leave people hanging if you, if you open up an issue or or submit a pr, we do really want to take the time to look through everything that we can, and so we didn't. We wanted to make sure that people weren't going months before hearing from us, and so we planned for that outcome as well.

B

um But we've we've had a pretty steady stream of um of contributions and it hasn't been too overwhelming, which has been nice, even though we are part of hacktoberfest.

A

Nice um is there any specific challenges you wanted to mention on this journey.

B

Yeah, there's been a lot um I mentioned localization.

B

That's definitely one challenge we're not accepting localization content for contributions right now, and um but we will in the future- and that would be amazing, because we can then get a lot of localization's one of those things where you want input on how things how language is structured and there's various different opinions on all of this, and so we want to incorporate a lot of that feedback into how we think about internationalization.

B

So that's one challenge that we're currently working through another one. That was really interesting. We document, like I said we document everything at github, and so a lot of that is uh features that aren't released yet, and so, even though these features might be on our public road map- and you might know a little bit about them, we document all of the nuts and bolts about that feature that product, and so we do that in.

B

We have two different repositories so that we can kind of maintain this internal to github before something releases content and then content that is fully public and eventually it'd be nice to just have content. That's fully public and get rid of our um our internal repository and we'll get there we'll phase that in when it's appropriate.

B

But we have a what we do is we use github actions to sync bi-directionally between these two different repositories, and so um every 15 minutes, or so the two main branches will sync and all of that content gets gets shared across them figuring out that workflow was really challenging because we have we have automated tests. We have actions, we have all kinds of different things that go into just publishing into our docs, because we use docs docs's stocks, our code and that's how we publish and so figuring out the synchronization between these two different repositories.

B

One internal one, one public was pretty tricky, um and so that's actually, where we spent a lot of our time over the those those um from june to october kind of figuring out making sure that this was going to be okay.

A

I actually think this is pretty standard for like any open source project, because either it's it's something like a secretive features that you don't like are not ready to release yet, or um sometimes people have security vulnerabilities that are fixing that are working on. They don't want to release it to the public and kind of zero day themselves into um some issues. So um I I think it's a very common situation to have the private and public repo for this. So I know you're documenting the journey in a few places, so would be super interesting.

A

I think for folks to read more about this and we'll.

B

A

Into the show notes, so folks can find out um some more about that um is there, um so it is, I know, github is everything open source right, it's a home for open source. We want to be as open as possible, but what does it really mean for docs like why? Why did we want to drive this to be a public project for.

B

Docs, it's really interesting, so docs are really they're kind of like a front door, especially for people who are new to github, and with that you come with a you, get people who are using our documentation that are coming from all different areas. They might be really experienced coders, they might be just new to github or new to get all of these different aspects.

B

And so one of the things that we wanted to do- and we talked about a lot early on- was the importance of community on documentation because developers are using our products more than we do they're using our documentation more than we do, and so getting a lot of input and feedback is really important to us. But taking that to the next level was magical because we could then once we open sourced, we could then have direct input into our documentation for what makes sense for various different, uh various different developers.

B

So there's things like, like the guides that I mentioned, that, um like the uh the pathway, where you could create your own article or your own guide, there's things like that that are happening, but there's also things like when you're approaching a new project or approaching a new feature and you're trying to learn how that works with a github product.

B

You want to see what other developers are doing, and so what we noticed was that a lot of developers were documenting like how to use how they use github actions or how they use github packages in other places, and a lot of that. Some of it is really powerful and it's easy to find, but a lot of it kind of gets lost and it's hard to find when you're starting out a new journey with github actions.

B

And so we wanted to really invite a lot of that input into github documentation to be able to share this information, and that comes from the community. And so that was a big. That was the number one driver for why we did. This was to to open open it up to the community because it's it was github's documentation. Now it's the community's documentation.

A

That's amazing, so do you want to show us what the process of contributing actually looks like yeah, absolutely.

B

Let me share my screen I'll just take you through really simple workflows, so we have been spending a lot of time with our actions, documentation lately and we've added a couple new guides and new areas and um for people to get to know github actions a little bit more.

B

So we've added a new quick start guide for actions that walks you through the super linter workflow, and so, if you haven't checked this out and you're curious about actions, it's really good for just kind of proving that you can use actions um which is nice and so I'll show you kind of down here at the bottom. It you know kind of at the bottom of the article you've already presumably gone through and you've you've created your your actions, workflow using super linter, and it's done so. I'm gonna just change.

B

Instead of ready to get started, I'm going to change this to want to keep going, because what we're doing here is actually giving you a couple next steps where once you've completed this guide, you can keep going so we've added this button here to make it really easy for you to.

B

Instead of having to go to the docs repository and navigate through our code base to find this article, you can click, make a contribution, and that will take you directly into the github edit screen for this, and so you can also obviously clone the repository and do this all of this work locally and our um contribution guides walk through all of this. But what I'm going to do, then, is just go ahead and make this edit.

B

And I'm just going to say, want to keep going.

B

Update quick start and I'm going to create this on a new branch and propose changes, and this is just the github workflow that I'm working in now um and our um we have a team of people who go through and um and respond to every single pull request every single issue, and so what we're using here is um is pull request, templates and so the the goal here is to figure out.

B

Why did you make this change and give us a little bit more information about what you did, and that makes it so much easier for our team to triage everything. uh For the sake of time, I'm not going to fill this out, I'm actually just going to create the pull request. I will apologize to the team later, but um I create this pr and what that does is it goes directly into our project for docs and doc's team reviews and it'll go right into the triage and, and then our woman.

B

I work with janice will coordinate this and make sure that my update that I just made gets into the right um gets into the right place and somebody's eyes get on it and probably what'll end up happening is the one of the writers. One of the original authors will chime in and say: hey kath, like maybe um maybe change.

B

This maybe add something, and so we'll go back and forth a little bit or maybe they'll love the contribution I made, and I explained it really well in the issue in the pr template and it'll get pushed through. But that's that's the easiest way to make a contribution to docs.

A

It actually sounds like a really easy flow and you're kind of guiding people through also how to submit a pull request in a way that it's meaningful and also it lands immediately in your board. So you can kind of step through the process of triaging it like looks like you have it all figured out.

B

Well, we want to go even further than that. I mean I think it would be really cool if, instead of using the github pr the github edit screen, um you could use code spaces or you could use something else to do something a little bit more meaningful, um and maybe you know edit multiple files at one time that kind of stuff. So we're thinking about that too, and actually, I think um there was a contribution. The other day that I saw a guy made, who he used github uh code spaces to be.

A

Able to do it, nice, that's cool. It's like programming on the fly right I can be in outer space, and I just like make contributions to github, docs and stuff. I mean you know, nasa's putting uh you know, uh network on the moon, so yeah.

B

We can do that. Well, while you discover water on the moon, you're also.

A

Submitting a florida class exactly I mean I think, we've had like contributions from antarctica before or something like that. So you know you can beat that now.

B

A

Absolutely um so, uh if folks want to get started, where can they read, and I saw that like right there, there was like about known how to contribute. Is there anything else that sort of folks need to know the best places.

B

In the github github.com github, docs repository and um reading through the readme there's contribution guides in there um that walk through a bunch of different ways to contribute, but um it also gives you a very simple just like here's: how to get started um and and here's kind of what we're looking for. So that's a great spot to get started, and um uh we can send some links for this for the for the notes, but um there's a great blog post that zeke wrote. uh Who is one of our lead engineers on the project?

B

He goes into a lot of detail into how we did this technically. That is a really good resource too. If you're curious, just about like what happened in those two years that we were thinking about this.

A

Right, nice, I love open sourcing journey, so this is completely awesome. uh So thank you for driving this change and you know absolutely that I think, is a huge change to the github ecosystem and people's ability to contribute to us and give us feedback on stuff, and you know, teach us how they learn.

A

So that's quite amazing um and of course thank you for being here with me today. I really appreciate it. This has been github checkout and please hit the subscribe button for more videos, bye.