How to not waste maintainer’s time during Hacktoberfest and still get your t-shirt.
Every year Hacktoberfest rolls around and every year we hear the same story. People open a lot of low quality pull requests on hundreds and thousands of open source projects with small changes like fixing typos in a README. This isn’t a super bad thing by itself, but popular projects often get a significant amount of pull requests like this over the course of the month, eating up a lot of the core maintainers time. The sheer volume of them quickly makes them go from low quality but harmless to unintentionally malicious. It acts like a human DDOS on the code review process. Maintainers still have to review the pull requests (or at least close them) taking away time from more pressing matters. So what can you do if you’re a newer engineer, new to open source, or perhaps both, and you want to contribute to a project that you think is particularly important? Or, and maybe more honestly, you just want the swag from Digital Ocean but you don’t want to waste people’s time.
Well, there is a never ending stream of work to be done on popular open source projects and a lot of the time that means existing work doesn’t get properly documented. Documentation is the way people are able to first figure out how they can use the project or if it fits the use case they’re looking for. Documentation is a way to evangelize a project to prospective users, help them use the project, and help contributors figure out how certain parts of the project work to make more contributions. Documenting part of a system is also a great way to get acquainted with that system yourself and prepare to then eventually contribute useful code.
Documentation doesn’t just have to be functional documentation like “how this function is called”, or “what does this do”. Docs can also include things like tutorials, sample projects, use cases, and even overviews of the project itself. However, which of these types of documentation a project accepts is not always spelled out to you. You can often get a sense of things by looking at the existing docs for the project and seeing how they handle examples. In the unfortunate case that there’s no documentation whatsoever, this is a little more tricky. You’d likely have to open an issue and communicate with the owner or core maintainers to figure out how to best go about writing some.
So, how do you figure out what parts of a project need to be documented, or need to have their docs improved? The easiest way is going to be to check through the issue tracker for the project and see if you can find issues raised around the documentation itself. If you do find one then check to see if the issue hasn’t been resolved, that it’s tagged with something like “help wanted” or “good first issue,” and chime in offering your help to sit down and document that section of the project. Maintainers will likely be happy to go over the documentation when you finish. They’ll work with you to answer any questions you may have, fix issues they have with the docs themselves and help you make your first merge.
If you don’t see any open issues around documentation you can try checking out the project’s existing docs and look for sections that exist but are bare. This tells you two things, first that it was important enough that someone thought to include at least a header for it in the documentation and second that they haven’t been able to get around to properly writing the documentation. This is a great opportunity to dive into the code in the project, gain understanding of that part of the code, and fill out the documentation to close the issue. There is also a higher chance that you will have some thankful maintainers when you do get around to opening the pull request because it will be something that someone somewhere had on the back of their todo list!
If you want to contribute tutorials or sample code showing how to use certain features you need to first make sure that this is something that the project is interested in. Follow their guidelines for asking contribution questions. Sometimes this takes the form of an issue on their source management tool, other times you may be asked to hop into something like Slack or Discord. The reason for doing this is that while some projects check in tutorials and samples alongside the code, others may have separate projects/repos for this (they may want you to contribute something there instead), and sometimes projects just don’t want that type of thing and it’s better to find out first. Remember, if you’re unsure about contributing it’s better to raise a question on the tracker instead of potentially creating a frustrating situation for both yourself and the project maintainers, and it’s more respectful of everyone’s time.
Helping open-source projects create better documentation for their code is a way you can easily get involved and help a project. This is true for both experienced and new developers alike. Writing documentation helps you dig deeply into the internals of a project and can be a lighter way of contributing. A way that is quick, very useful for the entire community, and still ends up with you getting your t-shirt without pissing a lot of people off. Who knows, you may even find that you start contributing more regularly (which would be great!). But if not, you’ve still been useful in a way that fixing typos will never be. You can feel good about the fact that you’ve helped a community instead of wasting their time to get a t-shirt. Hacktoberfest is an idea with its heart in the right place and I hope this helps you make meaningful contributions to the open source community.
Happy hacking!
— — — — — —
Docstring is a tool that helps keep docs in sync with code, determine where more docs are needed, and automatically update the documentation site when changes are made. Check us out, or signup to get notified when we publish more blog posts!
