Beyond maintenance

A consideration of how human-oriented investments are vital to a project’s long-term health.
Part of
Issue 9 May 2019

Open Source

It’s a subtle but important distinction, the difference between “maintaining” and “sustaining.” We can head to good ol’ Webster’s dictionary for more clarity:

main·tain (verb): cause or enable (a condition or state of affairs) to continue

sus·tain (verb): strengthen or support physically or mentally

While there’s a lot of important discussion in the open-source community on the maintenance of open-source software— from the mental health of developers to the financial stability of widely used projects— there’s not enough about their sustenance: how to improve and strengthen them. In truth, sustaining an open-source project has very little to do with fixing bugs or adding features and everything to do with people. In this article, I’ll share my perspectives as an individual maintainer as well as a member of the nteract community on how to sustain open-source products in general, and on what we’ve done to grow the nteract project, a set of JavaScript packages and applications for interacting with the Jupyter ecosystem, in particular.

Onboarding and workflows

Many engineering teams underinvest in their onboarding and development workflows. After all, new hires generally have an existing understanding of the technologies used in the product and a slight case of Stockholm syndrome with regard to the cumbersome aspects of the engineering process, like flaky test suites and long builds. Open-source projects, however, don’t have the privilege of neglecting this experience for prospective contributors; their success depends on a healthy stream of new people. Moreover, a successful open-source project needs to have a model for engaging all kinds of contributors: developers, documentation writers, designers, testers, security experts, and more.

As such, onboarding is the most important process to optimize. It encompasses everything from setting up a project to running and modifying the test suite to submitting changes back to the project. This process should be smooth enough to capture those motivated to make an improvement to your project, however small. People’s enthusiasm and energy for contributing to open source starts out relatively high and, as they encounter difficulties onboarding, that energy and enthusiasm decreases. Eventually, there isn’t enough to sustain their engagement. A comprehensive onboarding workflow should provide incremental success checks so that new contributors know they are on the right track. An example of a good success check is unit tests, which provide immediate feedback on whether or not a project has been set up correctly.

You’ll also need to capture and sustain the enthusiasm and energy of developers interested in contributing to the project’s documentation. Good documentation workflows should focus on making it easier to write. This seems like an obvious point, but it can be difficult to execute from a practical perspective. One of the hardest things about producing good documentation is that, often, you only realize docs are broken when you are using them. And because you are at work resolving your original issue (the reason you consulted the documentation in the first place), you are less likely to correct the error you’ve discovered—especially if it requires multiple steps. We added an “Edit this page” link to all nteract documentation, which directs the user to its Markdown file in our documentation repository. It’s a subtle addition, but it acts as a motivator and an entry point for individuals to make changes to the project.

Your contributor workflows should also include moments that motivate your contributors. On the nteract project, we try to post a “Welcome to the nteract party!” message every time a new contributor has successfully completed their first pull request. This shows them that they’re a valued member of our community and emphasizes the importance of their contribution.

A great contributor workflow reduces the friction that contributors experience between discovering something they’d like to fix and fixing it. It also provides success checks to let contributors know that they’re on the right track. Finally, it includes moments of recognition and motivation that make contributors feel accomplished and engaged with the community.

Branding and communication

Before you win a place on developers’ laptops and servers, you have to win a place in their hearts. Evangelism, advocacy, and branding are a huge part of open source. Think about the widely used open-source projects you’ve encountered: ReactDockerRust. Each has a strong, even iconic, brand identity.

Creating a strong brand is nontrivial. When you ensure that values and motivations align (for the most part) across your contributors and users, you’ll have effectively guided people with disparate skills and interests toward a singular goal. This is a monumental achievement. Few can get a group of people to do something in coordination for a common purpose. A strong brand identity goes a long way toward helping create and disambiguate that goal.

One of the best ways to align values and motivations is to write them down. You’d be surprised how many projects fail to do this. There are several ways to present your project’s values: a code of conduct (CoC), a content style guide, a README, and even contributor workflows. Convey these values in as many avenues as you can. It’s better to risk redundancy than to risk contributors missing the message.

The first avenue of communication is a code of conduct, which outlines the social norms and standards for your community. If your project does not have a code of conduct, make it a priority to adopt one! Recently, the nteract project underwent an audit of our code of conduct. The auditor brought up a great point: A CoC should not only state the rules of conduct but also explain why they exist. I.e., “We enforce these rules because we want to accomplish these things.” There’s no better way to showcase your values and how you plan on enacting them.

Also important are content style guides, which explain how projects communicate. In the nteract project, we adapted the open-source Mailchimp style guide into our own. It includes everything from agreed-upon conventions for spelling certain terms to instructions for creating different kinds of content, such as READMEs and docstrings, across our ecosystem. Style guides help build a sense of community and brand because they standardize the project’s voice across all mediums.

Most open-source projects have a README or website that serves as the landing page for new users and contributors. Since it’s the message people are most likely to see, you should include a description of your values there as well. Mission statements should communicate the what and why of your project to all readers, even if they are not familiar with the technical aspects of the project.

Writing things down is especially important in open source, where contributors are distributed across the globe. The shared vision and mission you communicate in writing helps build a sense of community among contributors and users. Your code of conduct and content style guide play double duty. They not only help you communicate your mission and values but also enforce the principles behind those values. However, writing is not the be-all and end-all: You still need to act on the mission you lay out.

You can also enforce your mission and values via your contributor workflows. If web security is a key part of your project, include a security audit as a success check in your developer workflow. If interactive documentation is a priority, include tools for providing interactive examples in your documentation stack. If you integrate these small changes into your workflows and standards, they’ll eventually influence your project’s culture and, in turn, its brand.

Inter­nation­ali­zation and inclusivity

Though contributors from the United States make more pushes into GitHub than contributors from any other country by orders of magnitude (almost four times as many as the next runner-up, according to GitHub Archive), nearly half of all pushes made from the top 25 countries come from places where English is not the native language. However, because we exist in a world where English is the de facto language for communication, most documentation is written in English, much to the disadvantage of non-native or non-English speakers. Heck, even the syntax of most programming languages uses English words. It’s so normalized in our communities that this state of affairs is rarely challenged or questioned. But the tide is turning. Vibrant developer communities across the globe—which have always existed in countries such as Egypt, China, and Colombia—are getting more involved in open source.

Your project’s messaging needs to be accessible to them. Offering documentation in multiple languages that appeals to a wide variety of audiences can seem overwhelming, but it shouldn’t be. Most web browsers come with built-in translation technology. That means you don’t have to write documentation in every language, you just have to write documentation that can be translated to any language by an automated translator. Use simple sentence structures, limit the amount of slang or localized jargon, and avoid ambiguity. If you’re looking for more ways to make your writing friendly for automated translators, consider reading Mailchimp’s guide on writing for translation.

It might seem silly for open-source projects to focus on emerging markets and audiences. Isn’t that something only well-funded organizations can afford to do? Do open-source maintainers even have enough time to address these issues? But it’s easier than you think. Setting up an inclusive and approachable open-source community in your own backyard makes it easy to reproduce the same inclusivity and approachability across oceans and mountains.

The secret

If you’ve gotten this far, it’s time I share a secret with you. There’s little difference between sustaining an open-source project and running a software team. The most important factors are fundamentally the same: having a firm sense of values and goals, taking care of the mental and emotional well-being of individual contributors, and being present in different markets. These overarching principles are enforced in the workflows and processes you implement for contributors, the code of conduct you enforce, the tone and style you use when speaking as a project, and the way you communicate with individuals locally and globally.

One of my favorite quotes, from the poem “Little Things” by Julia Abigail Fletcher Carney, goes like this:

Little drops of water,
Little grains of sand,
Make the mighty ocean
And the pleasant land.

In addition to being the answer to life, the universe, and everything, the poem also answers the question “How do you sustain an open-source project?” The answer: slowly, methodically, and incrementally.

About the author

Safia Abdalla is a software engineer working on open-source technologies at Microsoft and an open-source maintainer on the nteract project. When she’s not working on open source, she enjoys writing and running.


Buy the print edition

Visit the Increment Store to purchase print issues.


Continue Reading

Explore Topics

All Issues