GitHub Open Source Friday, 19 Oct 2020

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: docs.github.com - Open Source Friday

Description

We open sourced GitHub’s product documentation to help demonstrate that it’s possible (and beneficial) for private companies to open source their products. GitHub has open sourced hundreds of projects over the years, but docs.github.com is the first private production service that we’ve migrated into the open. We hope that our application design, automation workflows, and openness to external contributions can be a model for other organizations that want to open up their private projects and benefit from community collaboration.

Join bdougie and friends live for Open Source Fridays at https://www.meetup.com/GitHub-Virtual-Meetup

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
Google+: http://google.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

All right, unmuted, finally figure out how to use this thing um today is open source friday and uh we are here with a guest like normal nothing's different just the guest changes. Every week. I'm here we had a great evening last night with hopscotch and chatting about um apis, but today we're talking about documentation with janice, hey janice, hello, hey, janice, uh janice is coming in from uh well. You would think that was a virtual background, but it's actually a real background.

B

A

Excellent, so yeah, do you want to give us an introduction on what you do at github? uh What you do in regards to documentation as well, and even how you got here.

B

Yeah so I uh recently transitioned into being a product manager at github, uh and I am working on the docs open source project, so we just opened source the docs a week and a half ago, and it has been a whirlwind experience ever since then. uh Before that I was a content writer. So I was a technical writer at github uh for about a year and a half, um so I've been there for a while in tech time before that.

B

Like long ago, I actually have a degree in theater and worked as a middle school and high school theater teacher and then got into tech through the outreachy program, which works with people from marginalized groups to get into transition into tech.

B

It was one of the few places that would help somebody that wasn't a student get into tech, which was what I was really looking for when I was looking to transition, and then I worked on gulp js, which is another open source project uh and then found my way to github I applied and never assumed that anyone would like read my resume. Let alone hire me, but here I am.

A

Excellent yeah and um um yeah, it's fascinating that transition, and we, we literally just talked with megan last week from gatsby about uh their transition from going from teaching to also doing documentation, which it seems to be a common thread and I think, with documentation.

A

There's a lot of teaching that happens. Correct.

B

Oh yeah, so when you're writing documentation, you really focus on your user. You focus on who is reading your docs and how they are going to access the information and what the progression is so there's this concept in education called background knowledge and like what does your user know already and what pieces do you need to fill in and if you don't understand those things as a technical writer like you're, just not going to write great docs.

A

Yeah yeah indeed and um yeah I I appreciate good documentation. I I I enjoyed gatsby's documentation. I use a lot of github's documentation as well um as uh gatsby's.

B

Documentation is beautiful. It is some of the first great docs that I read that are more accessible to new users than I think anyone else's. That's like a missing piece in this open source world is like brand new people.

A

Yeah, I was going to say too as well the um so I used to work for a company called netlify as well, and we have a great documentation engineer as well, um which you might know jessica over there. um uh What I think she has actually has a team.

A

Now at this point, uh I I worked when we were much smaller, um but I think, even when we were creating documentation at that company, we looked around and tried to figure out yeah who's doing it well uh and like we named a couple of folks, and just always, it's always great- to see people doing it well, and people actually taking like the education piece of it and like taking people along for the ride um like with great care and that's what.

B

A

With github stocks like, I know how to reference things and I've seen, github stocks also um evolve as well like if anybody's um anybody's seen the github docs recently, um you can see it looks quite different than what it used to like. Even what six months ago, uh which I'm super.

B

A

um Shout out to zeke who's in the chat too welcome man who's on the team that does the engineering for the docs.

B

Yeah zeke has done so much work, getting us to the point of open source. If you want the nitty gritty details, he wrote a amazing blog post about how um we worked all the way through, like this has been a multi-year long process to get open sourced, and he explained how we got there in a blog post wednesday. It shipped wednesday.

A

Oh nice um yeah. I thought that was gonna happen. Let me uh re re-paste that link uh what happens is uh we actually have to block links for folks? I tried making zika vip before he posted that and then uh we had a race condition, um but yeah we'll get you we'll get you in there and zeke, um but yeah.

A

What I'm getting at is the um yeah there's a lot a lot happening in the github documentation so since you've been working on it for quite some time uh like what's some sort of highlights and the changes that we've seen not just open source but just seeing it within the documentation, like any sort of things that you want to point out.

B

Yeah so um I think about six months ago we went through the process of we had two separate documentation sites. We had a developer.githu dot docs. I don't even know what the website was anymore. We did a developer site and I had like api content and more of that and integration stuff, and then we had the regular site- and there was this- disconnect that users didn't even necessarily know that both of these things existed a lot of people used, one or the other, and so now they're all combined into this docs.github.com site.

B

So you can find everything you need to to use github as well as you can um in one place, and so that was a huge, huge effort um figuring out how to make all of those things work together. We've also done a lot of work, localizing content, so at the very top there's a language picker, and so we have yep, there's english and simplified chinese, japanese, spanish and brazilian portuguese, and so um you can see these docs all in different languages, some of them.

B

So we work with an integration called crowdin, and so when we update content um the writers update content and then it goes to crowded and then our translators translate those things and then they come back. So sometimes there's some lag depending on on what we're working on.

A

Okay, yeah so like when I'm looking at this, I see uh the giant, simplified charities here and then uh this is being in english. Oh looks like I got this 503 all right, not sure.

B

What happened there.

A

But here we go open an issue.

B

There we go seek fix it uh yeah so sometimes it'll be in english and that's the reason. Unfortunately, we're not taking uh localization updates in the open source repo, yet we're working to get there, um but with our crowd and integration that just doesn't quite work yet we're not there.

A

I was about to say I don't know if I could switch back to english. I can't read this.

B

You can you, can you can do it.

A

Yes, I just had to put my mind to it: um yeah if you, if anybody, has questions about the documentation and specifically feel free to drop in the chat zeke's here for a bit answer questions. um If you have a support question, which uh I think berea bradley brief for adley um feel free to drop it in support. I don't. I can't really answ like answer github linux in the gui um honestly can say no idea, um but it's a semantic pull request. I use that actually is made um grab a man's a fork.

B

A

Yeah, actually yeah dota is actually he has a pr than one of my projects using semantic pull request um or yeah the semantic pull request stuff um so yeah good to see you dota and um but yeah in regards to the documentation. That's um that's huge and that's that's pretty cool to see um the different languages.

A

um I want to talk about. Oh sorry, go ahead.

B

Nope, I wouldn't say anything what.

A

Are you saying well, it seems like I'm saying everything right now, but I was just going to talk about the fact that we just open sourced the documentation. Last week, yeah.

B

Yeah last week it was only last week, um even though it feels like it's been three years. It was last wednesday, um so this is. This was a really cool project right. So we actually excuse me we're working in two separate repos. We have a docs internal repo, where we're still writing documentation that isn't ready to be public yet, and then we have this public docs repo and we've got this great application called rebosync, which is also open sourced, and it takes the two and syncs everything together.

B

So the git commits commit history and everything in the file structure, all syncs between both repos automatically using actions. um So we can work in both places and we can get all of these great open source contributions and we can still do some of our work behind the scenes that needs to be done.

A

Excellent repo sync, you know it's funny. You bring this up because I was actually writing something for this and um you know hold on. Let me uh fix zeke again because I feel like you're gonna, have a lot of knowledge bombs to uh to share with us. Do it zeke.

A

All right, sorry, we're gonna, we'll figure this out. Oh there, it is.

A

Yeah, I think in the future we need to. um Oh, he keeps you keep beating me too uh beating me to uh trying to get you one of the valuable players within.

A

Why is bonnie okay, yeah, so zeke? We won't be able to do um to do any more link sharing, but um perhaps you can slack janice and janice can um can help us out there um but yeah for now we'll we'll move on uh to this, the repo sync and the reposting being also, I think I could probably just copy and paste that link again for zeke he's gonna he's taking time out of his busy engineering schedule to get banned by a.

B

Bot yeah we've been having uh our own thought issues. uh Bots are always so good until they stop working.

A

B

A

And speaking of bots too as well, so it's funny that I see this and like we literally work for the same company, I was writing something um it's very similar to this. uh This reposting thing, which okay mine, I don't think my project really uh it works that well, uh it's pretty inconsistent, uh but I've had to do the same thing where I need to sync the repos across different um organizations, um because we're yeah don't have to go into details but yeah. I am going to uh save this one for later.

B

Yeah yeah, so zeke found a similar open source project. I think it was called paul by a user named way and we worked with him and he created repo sync um to do all the school stuff for us. So it's open source and anybody can go snag it and do I think it's at doc, slash repo hyphen sync, um and so anyone can yeah. It's.

A

Are you talking.

B

A

uh The repo itself.

B

The repo sync is there, so we have another org called docs, which is all open sourced and repo sync lives in there.

A

Yeah, actually, let's grab the uh github. Oh interesting.

B

A

B

This is where our liquid markdown, which is how we version things and I believe, repo sync, is in here somewhere.

B

Oh man or I'm going to be wrong.

B

A

Right, oh so it so zeke's in here and he's spelling out he's learned his lesson and he's now spelling out the links for us. Okay,.

B

A

Is appreciated, thank.

B

You I couldn't remember, I've stopped my head there. It is.

A

B

A

Yeah in the future, we'll have to get a list of folks that we need to actually get into mod level. um So that way we don't have to. We don't get stuck uh in bot jail.

B

Yeah, so this is the project, anybody can borrow it and use it. It's got some some great docs, I believe, written by zeke and way uh explaining how to use it to sync, your repos.

A

Yeah and real quick, I'm gonna answer that that one question uh which do we have a calendar uh for future streams and that's a great question. um I think that was a small brute. These uh twitch handles always get me.

A

I actually pronounced one earlier today was uh kind of a tongue-in-cheek joke, and uh I regret saying it out loud, so I need to slow down a bit but uh yeah. So going back to our share and talking about repo sync, I just dropped a link to our our meetup page, which we do plan ahead. um All these streams and the the events that we do uh specifically the virtual events.

A

So it encompasses not just what we do on twitch it does what we also do on youtube as well, so check it out, join that group and um pretty good pronounced. This is a smaller boot, all right, excellent um yeah. So repo sync is now it's its own organization and its own repo keep a pair of github repos syncs, which is genius and zeke being the uh the prolific open source, contributor and maintainer himself has graciously put this in a place that we can all share and delight alongside of it.

A

So since we spent so much time just trying to get to this page I'll drop that in the chat too, as well.

A

Yes, welcome in uh julaz zordak 17. good morning yeah. You know I just lead into these names. I say I'm out loud because you know it's your name. I I honor your choice and uh I I will welcome you into our community here on the github twitch channel.

B

We need a pronunciation button so that everyone can explain how to pronounce their handles so.

A

There's um currently right now, clarkio is actually live streaming over on twitch and he's been doing a lot of. um He works at the microsoft team and does a lot of um live coding actually on fridays. Actually around this time and he's been doing text to code, not text code voice to code.

A

So I think you could use the uh like the azure cognitive voice thing and uh be able to do that way. But if you do the inverse text to speech, I think I can actually write a command to make that happen. uh I spent some time I spent some time making some twitch integrations in the last couple weeks.

B

They're always wrong, though somebody always says their handle in their head differently than I assume it is, but that's.

A

B

A

That's the fun of it, though, like leading into it: okay, yeah yeah. We we took a took a bit of a detour uh talk about reposting. uh This is literally a lot of action. So um folks, if you wanted to see a project that is using actions, um triage issue comments.

B

Yeah, so um we the goal is to set everything up, so you know we want to be really responsive and be available for all of these awesome contributions that we're getting and so right now I am the person triaging and uh the goal is that I don't always have to be the only person triaging, the primary person triaging and that people can dip in and out and participate in that. um So this action takes everything. uh I think this one's new issues, uh new issues, reopened issues and issues of new comments by contributors.

A

B

It throws them onto a project board which is also public and adds a triage label. um So then, I see those in the project board and I can take a glance at them and figure out what team from the docs like what sub team on the docs team should look at the issue.

A

Yeah, that is, uh that is amazing, and uh I'm a big fan of leveraging actions to do some of the automation. um Actually yeah. I've been doing a lot of talk about actions recently and uh always looking for examples, so I might be uh stalking this uh project pretty heavily in the future.

B

Yeah yeah there's a bunch uh of our trade, all the triage ones are together and then we also use a lot of action, a lot of actions to test um and make sure that prs aren't going to break anything. um We've got a lot of actions going on.

A

Yeah yeah talk about actions. I see at the the l11y action as well, which I assume is testing just uh interaction, um thinking the search too as well. uh That's a nice one that I get. I guess.

B

A lot of people.

A

Don't think about like hashing searching um and it looks like algolia is the: what power is the search um shout out to them? Algolia does they are great.

B

uh So everything one of the big things is that when we we have a staging. So if you open a pr, um you can actually see your changes on a staging server which also pops up automatically um and we kept forgetting that you have to actually uh push your changes. Let's see about pull requests, yeah, that's an article and if you scroll down, uh keep going.

A

View deployments on the right.

B

Side yeah welcome back, is great right. There where'd you go right there that view deployments on the right side and that'll. Take you to a staged version of the changes, and so you can see all of your changes for real what they really really look like, and you can click through any article and the only thing that's not going to work is search because you need that action to run algolia before.

A

You can see those changes yeah, it's kind of pretty janky there yeah.

B

Which makes sense.

A

Yeah, uh just real quick if people did not really realize what just happened here. This view the deployment. um I know this because I actually gave a whole github universe, talk about the deployments api um and it's a way for you to actually see the environments um that are literally on for your your environment. So um for free you get this for get up pages, but it looks like we're using heroku uh in this instance uh looks like.

B

Someone turned off the.

A

Environment side, which is fine, but uh normally if the environment side uh list was actually enabled, you could see all the uh deployments that are active um yeah. You can see also down here. You can see the latest environment which is gonna link from here as well excellent. I.

B

Love that heroku has integrated.

A

That in their bot.

B

Yeah, it's been, um it was really important for us, so as writers on the writing team. This is something that we use a lot. You know you make a change and especially because we're writing in markdown, if you're doing something like a table which can get so complicated and silly if you have a space in the wrong place or you forget a pipe, your table is just completely busted so being able to go in and actually see that uh on the staging environment and really understand what your changes are and compare them to.

B

The existing article is really valuable and we wanted to make sure that our uh our contributors could have that experience as well.

A

Yeah excellent yeah, I mean it's, it's always good to know like, and I love that the you have. The welcome bot you've got other things to help like help. People uh zeke just turned on the environments in the sidebar as well. Wow asking yourself receive 371 environment so like this is an active project right here. This is what I was looking for.

A

Zeke being the uh one of the admins on the the repo can do this for us uh no need to actually go and check this, but more of the for the the listeners who were not aware that you can actually set with the deployments api. Your different environments uh definitely take advantage of that. I built. I know this because I also built one for netlify, which is called loglify, which you can get your your netify logs uh directly in the environments. um It's a homework for the the listener to go.

A

Google that I won't continue to flex my own stuff, but uh uh small, small brute you, you ask about the neural search um stream coming. uh If you know somebody feel free to enter us. This is our our github meetup invite this is my twitter as well.

A

uh So you can reach out to me directly if you know of a project, I'm happy to reach out to them and talk about it um so far, we've actually I've asked all my friends to come on and talk about their projects, and um so I'm happy to make new friends and talk about their projects as well.

A

Dota dota 2 is to say the more environments, the better right. It's like pokemon, yes, indeed, yeah, and I love this um like being able to contribute to the documentation in positive ways what are sort of like low-hanging fruit, for people to contribute to like what are like the biggest needs for the documentation. uh Today,.

B

So um we've got a couple of areas of focus. So uh if you look at the issues, we've got content issues which are things that change the words on the docs page and then we've got engineering issues which are focused on the site, or maybe actions or workflows, or something like that.

B

um So those are all available depending on what you feel confident about our site is mostly, you know, you probably need to know some javascript, some yaml, um it's written in it's a node app um and then our content is all marked down with some liquid versioning. So the goal was for that to be really accessible and available to people who are maybe trying out pull requests and issues, and all of these things for the very first time.

B

I know that it can be really overwhelming to try to start figuring out how to get involved in open source and and get involved in github. So any content issues that we've put out we've tried to give sort of an understanding of this is what the change is and- and this is sort of what we're looking for in that change and then you're welcome to open a pull request. And if you have any questions, you can open a discussion.

B

um Ask in your full request. I am there. People have been confused and, and I understand it is a lot to try to figure out all at one time.

A

Yeah and like I feel like the best way to get involved in open source, I mean for me personally, I know uh past uh performance is not uh guaranteed for future growth, uh which I have a finance degree. I don't know if you can tell, but um what I'm getting at is that I like using the things uh and by using the projects I'm able to um so I'm now seeing dota's comment about friends in 2020, what a serious brag, which uh you know we're we're all going through different walks of life right now.

A

It's just it's challenging um and uh I'm just lucky. I work at a company like github, where I get to the zoom call people all day every day um which that doesn't sound like a brag. It sounds like a anyway I'll move on, but what I'm getting on is like using the documentation and finding like places like if I, if I spend a lot of time in the actions documentation to be quite honest- and I also realize this is uh this- is the stage version look at that.

B

A

Yeah, so I spent a lot of time here uh just looking for specific stuff. um Honestly, I haven't even seen this quick start.

B

Oh, we just redid the whole actions landing page, so everything should be maybe a little bit easier to find exactly what you're looking for so.

A

B

Been a new new thing.

A

Yeah excellent yeah that what I was getting at too as well, I always know kind of what I'm looking for, and the one thing I look for pretty quickly is usually um not managing. Oh this one, which I'm glad it's linked. I actually I used to just google from google.com uh events that trigger workflows, because I knew I could get to it eventually, but.

B

And here it is, it would just show up in the search results.

A

But yeah now I know I can just click two clicks and I'm in, uh but I look at this all the time. So when I'm building new actions, I just want to see, what's available to me, uh shout out to workflowrun. I just learned about this one recently, which you can actually trigger workflows from different files uh directly in the repo um but yeah I've just kind of blown away on how easy it is to learn things like actions.

A

How easy to find all the the information I need co-located in the right place, um so yeah shout out to the.

B

A

B

And we we are humans, so sometimes there are typos or there are problems and if you're on a page- and you see a problem like that, if you scroll down to the bottom, we've got a button there for you to make a contribution, there's actually two buttons. um This is a massive massive article, uh so there's a there's a make a contribution button um there.

B

It is, and if you click that you'll get into the edited version of this page on our doc site, so you can actually go into the repo and you can make a change and open a pull request, and then I probably will be the person who sees that ping and comes in and says oh. This is so great. Thank you so much.

B

Let me triage this for the right team and then the folks working on actions who know way more about actions than I do, we'll look at it and get it merged for you, you're gonna. Do it? Oh, no you're one of those people I'm making random emoji. Nobody needs pizzas and action. Docs, we'll.

A

We'll see if this gets pushed through, uh it looks like I can't commit the main we'll need to get that.

B

No, no, please don't commit to me on a friday. This is a very important.

A

Change I'll back out of this change, we don't we don't actually need this change.

B

That's okay, but there you go you you open your change and open a pull request and then and then we have a conversation and you can check it all out. um Please please use the pull request template. We, we have a template, we have templates, please use them. They're.

A

B

To make my life easier, so then I know what you intended with your change and where to send your change to people who know what they're talking about.

A

Yeah and if folks didn't know that you could actually set up a pull request template by um creating a pull request, template file, and then it looks like it looks like this. So this is. This would be the context that you have to fill out um if.

B

You click raw there's, actually a lot of details in there explaining all the pieces so.

A

This is this: is the.

B

Secret, so I've got a bunch of html commenting, so it explains what you need to do, but then the only thing that you'll see is those those other pieces.

A

Yeah excellent yeah um yeah, the the markdown comments is something I've taken a lot of advantage of um trying.

B

A

Project that I am taking contributions on for hacktoberfest I've been trying to push people or not push them to sort of like guide them into some new features and github that they might not be aware of like linking.

B

A

To the pr's by using the those tags um yep, so I I I finally figured out how to word my comments in a way that this is something to pay attention to, and actually please right, fill in this. This part, as opposed to right, like read over it, um I've been touring, I know, there's a couple actions and a couple bots that actually validate the copy of your template and then like we'll, leave a comment. If the it's invalidated, maybe someone deleted something um I feel like actually so dota2 who's.

A

Actually in the chat, I still have a pr open for you. um No, I have a pr that you open for me uh that I looked at this morning when I got distracted, but um I'll give you some comments uh this afternoon for sure.

A

Actually, yes,.

B

Trying to think of what other, so we spent a lot of time really focusing on how to make sure that anybody could drop in and hopefully feel like they could contribute. I know that it can be really. I personally felt really intimidated the first couple times I tried to contribute to open source. I was like, oh my gosh. What, if I do everything wrong and then they hate me, and they don't want to accept anything.

B

They don't even read my pull request so um yeah, I just didn't a lot, and so please don't feel that way. Here, uh someone even opened a poll request. That said, I'm practicing it's! Okay, if you don't want this cool great practice here, it's okay like please. Let me know that you're doing that and not just a spammer, because you know we get those right now too.

A

Yeah, no it's um I I don't mind people testing out the tires and sometimes people test out. You know opening up issues and uh leaving like one line changes or a one-line request, uh which is fine. Like it's a it's a great way to say hello.

A

um I will go ahead and close that and like point you to the discord like, I have a discord: um the chat with people to keep them connected and updated like what the plan is for the project, but speaking of discord, uh I see this discussion, uh which is github discussion. So I'm curious. What do what do? What I expect for for this area and like what sort of content is here.

B

Yeah so the idea with discussions for us, um everyone uses discussions differently. um So we've got like a hello welcome here and then everything else you know if you have an idea for how you think things should be changed. If you have a feature request, if you have a question, then feel free to open up a discussion where both the docs team and the community can participate in the answer and figuring it out and hashing things through. um We had somebody open up a.

B

I think that what does this notifications mean here so somebody went in, they had a conversation about it and then the end result was. Oh, you know what yeah. Why don't you open an issue about that? And so then the person opened an issue and and then we can get that fixed.

A

Yeah, that's awesome.

B

Yeah discussions are a really good place to have that conversation when you're not sure whether or not something is an issue. We've been sort of thinking of issues as a sort of a task list of the things that should be done or could be done so.

A

What's the um I guess, what would the boundary and I guess, since uh you're helping uh product manage this as well? So what's the boundary from maybe there's something not clear in the docs like? Should I go to support first to ask the question so like actually github.com support and say, like I don't know if this works or should I go directly to the docs to say this is not documented or yeah.

B

So um if it's something about your account personally definitely go to support because we have no access to anything of yours, um but if it's like, I don't understand what this line is supposed to mean, or am I interpreting this correctly or I think this might not quite be right, then feel free to come open an issue. The answer might be yeah. It is documented right and here's some more explanation about it.

B

Do you have a question like we can chat about it, um but yeah, probably an issue or a discussion feel free to do a discussion.

A

Excellent yeah- and I just wanted to point out with discussions- you can get your questions answered. uh So if you do have a question you can see um object. um He asked a question. We have an answer, um so it looks like felicity, I'm not sure content writer github I've actually not met felicity before. um Actually, I think I know who.

B

A

Yes, I've definitely seen them around, but I've never actually had interactions with them.

B

Yeah uh the best, like my favorite thing about discussions as a medium for questions is that those questions still exist. So if you have a question, I almost guarantee that someone else has the same one. So if you put it in a discussion and we find an answer, we can mark it as an answer and then, if someone else comes in looking for the same information, there's a spot to go.

A

So I do have a question and it's something: I've wanted to ask the actions team, slash the docs team and it's something.

B

I've always wanted.

A

So, okay, maybe I'll this- will turn into a discussion eventually, but my question just being a heavy actions: user is the github token that you get provided. I just want to know what the the ceiling is for those for that github token, I'm not sure if that's actually documented anywhere within the actions- and I.

B

Have literally no idea, let's find.

A

Out you go permissions for okay. I think this is exactly what I wanted, so this is. This did not exist back like probably six months ago, when I start really started turning up the the heat for actions, but just simply knowing what can I do with? The token is actually what I wanted so um hats off to me for never searching this and then finally, seeing what I what I wanted.

B

So I mean people think of docs as being sort of a static thing for the most part and they're not we've got, I think, 15 writers going at it all the time. They are constantly writing updating, changing the docs and that's something that's not necessarily visible to everyone with how big our documentation library is like.

B

You can't tell that this one article was updated unless you happen to go back to it um so having the repo open source like gives you a little bit more insight into that, um and then there will be cheat like we're looking to make some changes so that everything is a little bit more interactive and maybe there's some some wiggle room there and figuring out how that all looks.

A

Yeah excellent yeah I'll be uh so I bring this up because I've been doing some um some training. Actually, I have a training next week for actions and I've been wanting this, but I didn't want to go through and try to well. I do have access to look at the code, but like it's going to take me way more time than just asking um yeah but like having a chart like this is exactly what I needed um to be able to say. This is.

B

A

Limitation or the extent of what you can do, which is all I needed, um which I'm happy this this is so serendipitous. I had you on the rubber duck dust with me.

B

Yeah, because I don't know what that is at all.

A

Excellent well, we'll have to we'll have to get you some github actions, training we'll get you writing actions in the repo pretty soon I wanted to transition real quick, um because you had mentioned this in your intro, and I wanted to give some space for outreachy.

B

A

So, do you want to explain what outreach is and how you were involved.

B

Yeah, so um there are a lot of programs that are really big like google summer of code and some other things where folks can come in and spend like three months working with an open source project and get paid for it. um But outreachy is different because they work with folks who are not students and that's not really a common thing. uh There are lots of folks who are looking to transition into tech, and there aren't as many opportunities and outreachy creates that opportunity for people from marginalized groups, um they're global.

B

uh They take global the ba ba they accept applications globally. Words are hard, uh and so I worked for an or I worked with an organization called sisters which is uh the community portion of the anita b org foundation that puts on grace hopper every year.

A

B

um And so there's they put up a bunch of projects. I think they might have changed it a little bit, but basically you put in open source contributions and you end up working for an organization that has applied and been accepted to participate in outreachy and you get paid actual money so that you can afford to do this. Internship, which was a big thing for me, um and it was. It was a really cool experience. It got me a lot more comfortable with github.

B

It got me a lot more comfortable with asking questions publicly, which is a big part of open source, but can be really intimidating at the beginning um and it really sort of led the way into working with gulp and then working in github.

A

Cool- and you mentioned that in transition too, as well you so you worked with gulp, specifically in documentation.

B

I did, and so I, uh if you click that get started at the top, um we rewrote all of the documentation, put it on the site for the version for version four of gulp, and so uh the lead maintainer, and I wrote all these docs to get. Everybody started working on gulp.

A

That is that is awesome. What a what a nice introduction to to github, but also to even open source too, as well and like kind of full circle for you, because now you're you're doing open source at github, which is pretty amazing.

B

Yeah yeah, it's been, it's been quite the long and twisted journey and took multiple years of um sort of flitting in and out of tech and not being sure that it was really the right place for me. um I started learning how to code and realized. I don't like it and didn't want to do it. It's just not my thing, um and I didn't actually know that technical writing was a job.

B

I would not call myself a writer, I don't like write stories or anything like that, and so the idea that someone was going to pay me money to explain how to do something was right up my alley and sort of trying to learn to program.

B

Help me understand enough background knowledge and base level understanding of programming that I can sort of read into what things are and understand how to even start researching something to document it.

A

Yeah it's so I spent the the last couple days actually chatting with a lot of new open source contributors, as well as people who uh broke into open source and like just in the the context of like hacktoberfest. I've been a part of a bunch of different events and just encouraging folks to get involved and like hearing that you, you found your way even like after uh uh I guess attempting, or maybe you did learn how to code um yeah.

A

I don't know what the yeah okay so a little bit umpu, though um uh learning a little bit of how to write code finding out that it wasn't for you and that you wanted to do something else in tech and like being able to use your skill set uh in different ways, and I think that's something that a lot of folks don't don't realize that there's a lot of opportunity to bring your skill set.

A

That's outside of programming, like you happen to be a teacher prior, um which has helped you and being empathetic for is empathetic pathetic, sounds that sounds like the wrong word, um but yeah. They have the empathy to understand the onboarding experience, and um how did you get connected with the gulp.js? Was that through outreachy, specifically directly.

B

No, it wasn't um so my husband is a javascript developer, and so uh what happened was that I was. I suddenly realized that he was getting paid to do way cooler stuff than I was and getting more money than I was as a teacher, and I was like I'm gonna totally learn how to do this. So I started using all of these free resources.

B

You know free code camp and I was doing some code academy stuff and some of the harvard mit classes and just sort of grabbing on to anything that I could to figure out what was interesting and what I might like to do, and he is friends with one of the maintainers of gulp, so I ended up starting just helping write blog posts. um I didn't understand what I was reading at all. He would write this blog post about very technical things.

B

I didn't know what it was, but I had just enough knowledge that I could sort of edit it over and say like well. What are you trying to say here? What's your purpose who's your audience? What's the goal and we could work together to create a blog post that was um accessible and usable and focused on on who needed it.

A

That's awesome yeah, I mean again so much serendipity in your story and how you sort of found yourself into doing that, and then I'm curious since we're on that this path, like specifically, how did you get into github.

B

So um I decided so I actually took the years that I was doing outreachy and um uh and working with gulp I was, I had very small children, so I have a four and seven year old. Their birthdays are almost and just happened, so I kind of forget how old they are right now, um and so I took some time off to be at home with kids and I was doing a lot of part-time stuff, and then I decided that I was.

B

I was ready to get back to having some sort of full-time conversation with adults and not small children, so I started applying at random places. I loved, um like I knew github I'd met people at conferences from github. I really really loved all the people that I'd met, and so I started just kind of creeping keeping an eye and then a position happened to open up um on the core content team.

B

Writing just all of the things um the core content team writes anything that shows up and isn't apis packages, actions or advanced security, and so every day I would sit down and write something different and I never knew what I was going to be writing about, and I probably didn't understand it before. I pulled an issue that I had to write some documentation and had to learn about it and figure it out and go from there.

A

Yeah, that's awesome and I guess my next question is like: have you rediscovered your love for coding? After you know, you've wrote about coding for so long.

B

No, um I was really into uh I really enjoyed doing some like front end work. um That's the small amount of work that I was really doing. um I made a really really ugly website for sisters which, hopefully no one ever finds um it's hideous, so I enjoy writing like css and html and that's about as far as I got and then and then I bounced and started writing words instead.

B

But I really like collaborating with people and technical writing lets you work with all these people who have expertise, but don't necessarily know how to transfer that into documentation. Just like in education, you can have these brilliant teachers who are so smart and so understand what they're talking about, but they don't necessarily know how to take 17 steps back from their advanced knowledge and write, beginner documentation.

A

Yeah, no, that is, that, is true and like uh the your interactions with the the gulp maintainer too, as well, is a lot of a lot of what I like about the the content writers. Even the copy editors to github. Is that sometimes I I I think I know what I'm doing, but sometimes a structure or just have the call to action. That's very clear, um yeah, I'm a big fan of like people teaching me on how to do this better and um yeah.

A

uh A hero too late um said that the quote the documentation is the love letter that you write to your future self, um which is like yeah, like my readmes, like my contributing guides, it's stuff like where I'm just like. I haven't done this a while.

A

Actually, I was just contributing to um um to node.js actually, and I was finding that um there was a there- was something different like to go in the really in the weeds, like there's a runtime called v8 and we had to backport it, um which is like not important details, but the the fact that the back porting and getting the get history to match with like what was up on github.com.

A

um There was no, it wasn't documented. It was kind of like a weird edge case that no one, no one like only a handful of people even do this, and I happen to not that I do it all the time it just happened to be the problem.

A

I was trying to solve required me to do this, so I kind of just hit edge case where it's like no one's gonna ever run into this, but then, when someone runs into it and they figure it out or they don't figure it out, then there's like I don't know, what's going on so maybe I'll just walk away from this forever and it would have been a shame if I did, because it was, it was actually pretty trivial to fix.

A

uh It just happened to be like one of those it works on my machine problems and uh yeah. I just needed needed a helpful extra pair eyes to help fix that.

B

Yeah that collaboration piece is, is definitely my favorite. That's what made um the idea of transit transitioning into product management? Appealing to me like the more people, I can talk to about all the things that they're good at and figure out how to make them all fit together. Like the happier I am so, uh it was a logical transition.

A

Yeah, so moving to speaking of transitioning, moving back at o1 pollux uh welcome. Welcome in thanks for the the love and the hearts as well um talking about the github documentation and being open sourced last week and ways people can contribute. um We just got. We finished talking about this uh github discussions being a place that we can actually um ask questions things that may be missing within the documentation. It's a good place to start um get up discussions.

A

It's a newer feature that was shipped earlier this year um that focus on well literally just discussing the project um so leverage that um also the fact that we have this now new make a contribution button at the bottom of all the articles. um It actually opens up somewhere like what we see like. We see this in a lot of different documentation, platforms and tools and guides uh you can actually make the edit. uh I love that it's actually a legit button too, as well, can't miss that well.

B

You have to scroll.

A

Down to find it but yeah you do sure, and not only we didn't actually even jump into the contributing guide either.

B

Yeah, so um we are excited about whatever kind of contribution you're ready to make. So if it's opening an issue awesome, thank you so much, and if it's opening a pull request, then that's great, um and if it's asking a question, then that's that's. A great way to contribute to um contributions are not just pull requests, though we appreciate those as well. um Our contributing guide also explains a couple things that we're not accepting uh contributions on right now, like localization and translated content, um and then we are struggling to uh take images.

B

So if you have a screenshot that you see, that is outdated, please open an issue, um but it can get really complex with our versioning, so our doc site is versioned for github server and all the different versions of github server that we currently support, as well as all of the rest of the end users. So those images can get wonky.

A

Okay, yeah yeah best to uh leave it to the uh the folks who can figure that out when they're in.

B

Yeah, but that issue is appreciated because we may not notice that it's outdated. Sometimes we miss those.

A

Yeah excellent and I'm curious, um so I did see the the call out to github desktop, I think so. Over here yeah you can actually fork using github desktop.

B

I love desktop desktop is my best friend.

A

Yeah, I I use it for one-offs, so for a longest time I always use desktop for my second account. uh I keep a second account for testing purposes and in order.

B

A

Contribute I don't want to use like the in get. You can do profiles, but it just becomes. Actually, I probably set up pretty easily if I just took the time, but what I'm getting at is like. I don't it's easier to download desktop. Also I like using a lot of different things, so desktop having an excuse to use it, because I spent.

B

A

Of time on the command line, um that's what I use yeah.

B

Yeah we had a really great intern. In the summer we had our first ever documentation, intern.

A

B

Yeah he got to redo this a bunch of the desktop documentation which he restructured and worked through. It updated some screenshots and just like made it all beautiful. um When I first started at github, uh git was really scary. For me, I'm not gonna lie zeke would back me up here, um I'm still afraid of get it terrifies me.

B

um I feel like it's very opaque, and so I'm always afraid that I did something um that I'm not gonna understand how to get myself out of and desktop is really helpful in that area, because you can see what you're doing and uh it can help. I don't know it's really helpful. There's also uh one thing I've heard a lot of people really enjoy is that you can easily add co-committers.

B

So if you work with somebody else, there's a little spot in desktop where you just throw their handle at it and it'll it'll populate it, for you and they'll be added to your commit. Instead of having to try to remember the syntax.

A

Nice uh do people call you jan ice.

B

In elementary school, of course, they did come on.

A

He he misread the name and thought it was jan ice, the whole time you never know what to.

B

Do well and the middle name spelling is just you know everyone's like. Are you sure you spelled that right.

A

B

I did he did spell my name correctly. Thank you.

A

The um uh also a shout out to your background too, as well, just remind their folks. That is a real background.

B

A

Agrees: it's real yeah you'll have the at the end of the call. You have to go, walk back and throw a rock over the ledge or something.

B

I don't think uh they'd appreciate that down in the driveway.

A

No yeah- probably not maybe, uh let's keep everybody safe for now, but we'll imagine it yeah excellent yeah, any other things you want to share about uh contributing documentation. The fact that it's open source, um some cool easter eggs.

B

um Come contribute, come join, us come talk to us, we love documentation and we're really excited to chat about it. So, even if you're not sure where your contribution should go pick something try it out. It's okay, just tell me you're testing things. If you're testing things.

A

Excellent yeah now there's like lots of jokes about your neighbors and throwing rocks the um so we do have a little bit of time. I actually wanted to ask you a question of what yeah, like you've, been around like seeing a lot of different projects like what are some uh real birds jealous?

A

uh What are the some of the the projects that you you're impressed with that are hosted on github and open sourced.

B

Oh, I so gatsby is one of my absolute favorite open source projects to look at and see how how well they're caring for brand new contributors um netlify. I creeped on netlify a lot too, like any documentation, so I write docs any documentation that focuses on brand new users that don't necessarily understand all the background information is my jam. um It's just that it's that missing piece like when I very first started.

B

I don't know what I was reading, but I was reading some sort of guide and it was like open the terminal and I was like I don't know what that means. You can't google, how to open the terminal, all sorts of random stuff pops up. It doesn't actually work. I didn't understand what was happening and like nobody would just explain that piece to me. um So anyone that takes the time and the care to really really get down and dirty explaining the basics is, is my friend it's my favorite.

A

Excellent, I just dropped in the chat. uh So last week we had a chat with uh gatsby talking about their documentation as well.

A

So if you want to learn about how they do documentation and how they structure their contributions as well definitely check that out looks like I there you go: here's a better screenshot how to reproduce errors exactly excellent and then shout out to um uh real quick uh brandon's in the chat and brandon was actually one of our earliest pilot episodes too as well. So since I literally just uh I just uploaded it last night, uh I'm gonna share it to you as well, so everybody can watch and share and enjoy.

A

It looks like I got my uh there. We go but yeah brandon, thanks for being one of our earliest pilots with the ngrx uh that was like back in the day when I even know what I was doing with the layouts and uh figuring out the whole streaming thing um still have the same. The same background, though it's exactly the same. It's weird! It's like it's almost like it's fake.

B

A

Excellent well janice um thanks so much for chatting documentation with us talking about um open source documentation on github um folks. If you have questions you can find janice in the discussions and the issues uh find janus on github as well. You know that's true the place where you can. You can hang out and um I just want to give another shout out to to our future guest. um So in two weeks we'll have interlinked lee talking about uh react.

A

Query uh I sort of skipped over our next guest, which is oh, no, it's actually our next guest after that would be next friday yeah. So we do have an apac version. So michelle who hostes the the stream in australia time uh because she's in australia she'll be doing handling the uh chat with tanner uh and then next week will be create react app with me.

A

So if you want to get in on the action and get notifications uh feel free to sign up for the group and we're just sort of funneling all messaging and notifications, there so check it out I'll drop a link in the uh the chat too as well. If you came later- and you missed my earlier link, dump so cool.

B

Awesome, thank you so much. This was super fun.

A

Yeah, it's fun. It's always nice to uh share the experience of how open source works. I know this is open source project- that's built on github, but like we are using the same patterns with the contributing md and the guides and issue templates. So I think if we were looking for a model for how to structure your open source project or gain contributors um there, it is and everybody.

B

A

Hit the follow button too as well. I should say that you hit the follow button on this twitch right now. So that way you get notifications and you can just forget about the meetup page. You just be surprised whenever we go live like christmas morning, every friday, all right with that being said, I'm gonna move on and uh yeah thanks again, janice.

B

Absolutely bye.

B