The Open Source Community: Documentation & Issues

[00:00:00]
>> [MUSIC]

[00:00:03]
>> Kent C Dodds: So now we're back to the community aspect. This is the stuff that I wanted to mostly talk about. So for the documentation side. A couple of you in the pre-event survey mentioned that one thing that you really want to get out of this workshop is how to write proper documentation for a library.

[00:00:20]
And so here's what I suggest. The first thing that you write about is what the problem is that you're trying to solve. How many people have heard of start with y, the concept of starting with y? It's fantastic. And it basically the premise is is what makes people really loyal to companies is those companies that understand why they're doing what they're doing and communicating that well to the people who are purchasing their product.

[00:00:50]
And in the same way I think we can communicate why to the people who are using our open source libraries. So document the problem. What are you trying to solve? And that should be one of the first things that you do. And that can be as simple as a single line of, when all you want is GitHub] names, this will solve your problem, whatever.

[00:01:15]
Or it can be a big long paragraph explaining what the problem that you're trying to solve is. And then explain the solution. So once people have identified, okay, I'm having this problem that they're describing. I totally get it. How are they solving this problem? Then they can determine whether they like the way that you've solved it.

[00:01:32]
And if they like the way that you've solved it, then they'll be interested in seeing how they can actually use it. So you explain how you've solved the problem. Once they decided that they agree with your solution, and they wanna use it, then you need to explain how they install it.

[00:01:49]
And installing is more than just run npm, install this. Lots of the people who are using your libraries are maybe new to npm, maybe new to Node. And so explain okay, you're gonna need Node version this and NPM version this, and you'll run this command after you have those things.

[00:02:08]
And make those links to what NPM and Node are. Be as friendly as possible to new people, because making things good for new people makes it better for everybody. And then you get into API documentation. Obviously you're gonna want to say, okay, when you require this thing, you're going to get an object that has an all property and a random property.

[00:02:28]
And the all property has all of the things and random will get you a random item. And here are the arguments you could provide to random or whatever. That's fairly straightforward. I think most libraries are pretty good at API, or at least documenting API. Another really good thing to document is examples, and make it really easy for people to add examples to your library, and ask people to provide examples.

[00:02:50]
If somebody says, hey, thank you so much for this library it saved me a lot of work, you can say, awesome, could you add an example? Thank me by contributing an example to the project. So an example could be something in an examples directory in your project or it could be if you've got a website or something, you could have examples that go on there.

[00:03:11]
Tutorials are really valuable, too, so we're all different and we can contribute to open source in different ways, so seek out the people who are using your project who might be good at creating tutorials, or create tutorials yourself. But through this whole experience what you're trying to do is not do everything yourself.

[00:03:31]
Even if you are excited about the library and you know that you can do this and whatever, hold your horses and try to find somebody else who is interested in doing it, somebody who actually uses the library. Because by doing that you're gonna start building a community around this library.

[00:03:50]
At first you might have a little bit of trouble doing that, and that's okay because you need to actually convince people to start using this thing, and sometimes it's like chicken and the egg. Sometimes it's actually better to have tutorials first, and then people will start using it.

[00:04:04]
But if you can, try to get other people involved in ways that they can be involved. Blogposts are really useful, screencasts, that's something that I really like doing. I like making screencasts. Just put it up on YouTube and then add a link in your readme. And then give talks, at meetups, at conferences, whatever.

[00:04:23]
And that's a great way to kind of give a high level overview of the problem. So then on the community site side of things, there are a couple of services and things that you can do to kind of improve your community as a whole. Chat is really great.

[00:04:39]
Gitter, anybody familiar with Gitter, used Gitter before? Here, I'll just show you, Gitter.im. We have technically 6 minutes left. I might go 10 or 15 minutes over. But yeah, Gitter's great, I like it a lot. It's good for interacting with other people and specifically on projects, and it's quite easy to set up.

[00:05:06]
And then Stack Overflow is underrated in open source and we should use it more. Generally, people will file issues when they have questions. If that's the way that you want to work your project, that's great, but I prefer to direct those people very kindly and patiently to Stack Overflow.

[00:05:22]
Because often, what you're gonna get are people who don't understand JavaScripts, are new to code, and that's totally fine. But if you want to avoid burnout, you can't teach every single one of these people how to use JavaScript. So send them over to Stack Overflow. If it's really an issue with your library, then you can actually give them a link that will add a question that's pre-tagged with something.

[00:05:47]
So you can add a tag for your library. And then you can subscribe to the RSS feed for that, add that tag, get emails, and make sure you stay on top of those Stack Overflow questions. But that way, the entire Stack Overflow community can help you teach people JavaScript, which is great.

[00:06:05]
Issues, obviously, leave those on. That's important. Pull requests, another really important thing to to be active on. And then here's just kind of a fun pro tip of something that I did with one of my libraries. So let's say you have a lib called yourlib. And you have the domain yourlib.com.

[00:06:27]
So often when you're working with a community, people are going to ask you for help. And one of the best ways for you to give help to people is when they give you as much information as possible. And so for libraries that work in the browser, this is fantastic.

[00:06:45]
Because you can set up a jsbin or a jsfiddle or something like a code pen that has everything all set up. It has your library as like a script tag. And it has kind of the scaffolding, and you just say insert your code here and reproduce the problem.

[00:07:04]
Or show me what you're trying to do. So then you have that and you point your help.your-lib.com to that bin. Or if you don't wanna buy a domain url that's totally fine. Just have a short url to point to this place for people to get help. And then it's really easy when somebody says hey, I need help.

[00:07:28]
You can just say, okay, thanks for your interest in the library. Just go to help.your-lib.com, and they look at the URL, they know exactly what it's for, they go to that. And then before they come back to you with a link to their reproduction, they're like, I know what the problem is.

[00:07:48]
And you never even have to answer their question. What I find often that happens is people have kind of a weird mix of things in their own projects that they can't reproduce outside of their projects. That's because they have different libraries that are in the mix. And by isolating it into a separate example, they realize what the problem is before they even ask you.

[00:08:11]
And what's better is for them to come to you with the actual reproduction of the problem. And so, all the while, you're saving yourself on burnout but you're also helping people take ownership on their questions. And you're also offering them a great deal of help and saving both of you time.

[00:08:32]
Also issues, so if somebody has an actual issue, then they can reproduce an issue in Jsbin, or if it's more of a server side thing, you can have a repo that they can clone. And they do this, too, a fork. Learn, so if you have a getting started guide, you can have learn questions so that autofills a Stack Overflow tag.

[00:08:56]
Changelog can go to the changelog, chat can go to chat, so on and so forth. So having short URLs has actually been really nice. Obviously, you know that I really like short URLs. I use them all the time, so that I don't have to go find these things all the time.

[00:09:11]
So issues, labels are really important. On GitHub, you can have specific labels to say okay, this is a beginner friendly issue or this is a really hard issue. We're probably gonna do this issue ourselves, or you can assign issues to people. You could say that this issue is associated with this thing, this part of the library.

[00:09:35]
You can say that this issue would be a breaking change. This is a bug, enhancement, whatever. It makes it a lot easier to organize your thoughts around the project. And even more makes it so that people coming into the project who are interested in contributing can organize through those issues and find issues that they can contribute on.

[00:09:52]
Having a contributing md file is great. And so if you're not familiar, contributing md file in your project, you just put it in the root of your project. And at the top of the issues page, it will have this little thing that says please review the contributing guidelines to this repository.

[00:10:11]
So you can say, hey, if you're gonna contribute an issue, that's great. Thank you for doing that. Here are some things to consider. Or it's also a good place to say, okay, if you wanna contribute to this, then you're going to the git clone, or you'll fork it, then you'll clone it, and then you'll cd into your clone.

[00:10:30]
And then run the install, and run the setup script or whatever. That's the place where all that stuff would go. Issue template is a sweet new feature that GitHub finally gave us, that allows us to prefill issues and pull, well, the issue template is for issues in the GitHub issue.

[00:10:49]
So when somebody goes there they can make sure that they provide all the information that you're looking for so you don't go back and forth. This is a great feature. You can just put that in the root of your repository, or you put it in GitHub/ISSUE_TEMPLATE.md in your repository.

[00:11:09]
If you check out the last branch for this workshop, you will see all of these things set up so you can get examples of them. Saved replies has also come. Take a look at that. I think I'm just gonna keep on going through this. So the same thing with pull requests.

[00:11:27]
The idea behind issues and pull requests again with kind of the idea of saving yourself from burn out and helping other people kind of build a community around this thing. Early on when I was doing open source I got really excited any time somebody reported an issue or filed a pull request.

[00:11:43]
It was like, sweet, I'm gonna do this now. I even had one time where somebody said hey, I've got this issue. And five seconds later I said awesome, time me. I'll have it released in five minutes. It took me nine minutes but I fixed the bug, I pushed it out.

[00:11:58]
It was tested and it was released in nine minutes. That is not a healthy way to run an open source project. Sure, they were really excited and they're like, yeah, you're the man, high fives, this was awesome. And it felt great, I was helping people, and that's one of the things I love about open source.

[00:12:15]
But it turned out that that particular library still has no owner. I'm not interested in maintaining it anymore. I'm not using it. I know that it's helping still hundreds, if not thousands, of developers right now. But it's just not something that I have the time or interest in maintaining.

[00:12:33]
But because I was so zealous about doing everything myself, nobody has really taken ownership over that library. Luckily, I have semantic-release set up on that library, so if somebody submits a pull request and it looks like it will be fine, and I've got Travis running the test and everything, I can just hit the Merge button.

[00:12:54]
It gets released, I don't even have to have it come onto my machine anymore, which is really nice. That's one of the biggest benefits for semantic-release for me. But yeah, get out of the way. Let somebody else hit the green Merge button, let somebody else solve the issue.

[00:13:08]
If somebody says, I found this issue with your library, you say, great! Would you like to make a pull request? And then you leave it at that. Archive the email, because this is our community, this is our code base. And if you're the one having the problem with that, I'm sorry about that, but we're working together on this.

[00:13:27]
Now at the same time, if somebody is new to the community and needs help, then you should be there to help assist them and/or other community members in your community should be there to help assist them with that. I think that's important, too.