Helping open-source contributors get started

Open-source software (OSS) is a big thing, and becoming ever bigger. Open source gives people the opportunity to contribute to large-scale projects, and it gives those projects the opportunity to gather expertise from the community of experts rather than being limited to employees of any one organisation. The documentation in an open-source project is arguably as important as the software. But it’s often hard for would-be contributors to know where to get started. That’s true for people wanting to contribute to the docs as well as the software. Here’s where we tech writers can help!

One of the biggest hurdles I’ve found as a would-be contributor is that I need to figure out so many peripheral frameworks and tools before I can even think about contributing to the core software or doc that I’m aiming for.

Framework upon framework

I’ve had this experience a couple of times recently. To make one simple change, I need to learn three or four frameworks/languages/tools. In the docs world, these frameworks and tools include Markdown, Django, Read the Docs, Hugo, Netlify, GitHub Pages, and so on. And then there’s git and GitHub… you get the picture.

It’s not even as if you have to learn a framework for each new project. Often the frameworks are stacked on top of each other, and you have to know them all just to make a simple commit to a project. For example, for doc updates a fairly common set includes Markdown, Git, GitHub, Hugo, and Netlify.

Engineers have their own frameworks to learn. On the web side, these may include Angular, Node.js, React, and so on. In the world of containerisation, there’s Docker and Kubernetes. And so on. Wherever you look, you find multiple frameworks piling one on top of the other. These frameworks add flexibility and agility to the software systems, but they also add complexity to the stack of concepts people need to absorb and the tools people need to manipulate.

Tech writer speaking: who’s my audience?

In this world of proliferating frameworks, what can we assume our readers know? The readers in this case are engineers and others who want to contribute to an open-source project. That means they want to make a change in a repository, test that change, and submit it for approval. This is true for the docs too: If a change is anything more than trivial, contributors need to test or preview it before submitting a pull request.

I think we can assume our readers have indepth technical knowledge of one or more languages or tools, but it’s unlikely they have indepth knowledge (or even any knowledge) of all the tools they need to do the job. And so, they come to the docs for help.

Too often, people have to go read the entire Internet just so that they understand how to make a simple change in a project.

As tech writers, this is where we can shine

We can give these tech-savvy people the information they to get started, and point them to more in-depth guides when they need them.

In short, we can show people:

• The tools our particular project uses.
• A basic workflow for making a change, including step-by-step instructions for the minimal operation of each tool.
• Where they can find indepth information about each tool if they need it.

If you’ve recently made a change in an OSS project, or are planning to do so, jot down the steps you needed to take. They’re likely to be what everyone else needs to do too. If the project’s README file didn’t contain enough information to help you, submit a pull request that updates the README based on your experiences.

Even if you don’t have a particular change to make, take a look at the README or contributor’s guide for an OSS project that catches your eye. Does it tell you enough to get started? Would you be able to make a change to the contributor’s guide itself, by reading what’s in it? If not, consider updating the guide and using that experience to compile the steps as you go. It’s a great way to get some OSS contributions in your portfolio.

Examples of contributor guides / READMEs

These are a couple of OSS contributor guides I’ve updated recently:

• The Kubeflow website project on GitHub. (Scroll down to see the README, or open the README directly.) It’s edifying to read the comments on my pull request. I went down the wrong track not once but twice, due to lack of … documentation. 🙂
• The documentation contributors’ guide for SymbiFlow Project X-Ray.

Other examples:

• The Kubernetes project has a nice README. I like the way it starts with a welcome!