My Open Source Journal

article by Mauricio Palma

Where am I coming from

One of the fields that I love the most about software development is the field of research and development. Usually, I pick or receive a topic and dive straight into it. I conduct studies, develop experiments, and all the fun stuff that reminds me of an alchemist looking for the formula to create gold. Other times it might feel a little bit more like Victor Frankenstein on his quest to create life.

Anyway, I continue iterating and validating my hypothesis until I find a feasible result. At the end of such a process, I usually end up with a small application or library as a validation of my research. I enjoy helping others to save time, benefit from it, and love to share my work. This is why I put it up on GitHub, feel all proud, and think to myself, I’ve created an open-source project!

Time went by, and I realized that my projects might be open source, but nobody is contributing to them, no bugs are being filed, no discussions are being held. There is not a community behind it. I started to wonder, why is that?
I had the great opportunity to showcase my work at some abroad conferences and expected that this might be the opportunity for me to gain contributors and create a community behind those projects I am so passionate about. But, no matter how hard I stared at the GitHub stars, contributors were still missing.

One day after a meetup in Berlin I met Ola Gasidlo, who is a principal software engineer with year-long experience in open source. She was willing to help me and take a look at what is holding contributors back. This is the journal of our journey diving into the world of open source from a research and development perspective. We used the Docfox project as a baseline.

Day one - The brainstorming

It has been around 10 weeks since I’ve been isolated because of physical distancing, and I am very stoked to have my first meeting with Ola. Honestly, I’ve been looking forward to this meeting for the whole week! The virtual chat has been set up, we are both preparing our coffees concurrently and having an incredible friendly chat. Creating a collaboration space where people feel comfortable and are having fun are the best requirements to get the best ideas going. 10 minutes into the call, and I realized I already had 5 pages of notes. There are several aspects I need to consider for my open source projects. Today I will give you a bird's-eye perspective of what these things should be.

Project 💜 contributors

Our role as project maintainers is to make contributions seamless, accessible, and a place to learn. This should become a place of inclusiveness, empathy, and collaboration around the projects we are building. We want to foster a healthy environment. Below you will find some bullet points of this bird-view and we will get into more detail in the next couple of days.

• README.md
  • What is the project about?
• CODEOFCONDUCT.md
• CONTRIBUTOR.md
  • Developer onboarding
    • Install
    • Development
    • Testing
    • Linting
  • Badges
    • Testing coverage (This is really important)
    • Build (pass / fail)
    • Deploy (npm / yarn in case it’s a released package)
  • Issues
    • First PR - issues for people who have not previous project experience and very little experience in open source.
    • Starter - issues for engineers with some experience in open source projects.
    • Regular - create a template of the expected outcome (issue template)
• Communication Channels
  • Support
  • Mentoring enablement
• Website
  • Guides
    • written in simple, inclusive language

Before we move on into the fun parts we have just discussed, I’ve learned that having an open-source project in a mono repository could prevent amazing people from contributing. There is a cognitive load implicated with larger codebases that are not directly related to the project itself. In other words, the time has come to move the Docs package into its own repository. We are splitting it from woodlike/wdlk to woodlike/docfox.

Day 2 - The README

The sun is shining, summer is full-on and we continue to practice physical distancing. The core functionality for the Gatsby Documentation theme has been written and I can finally show my progress to Ola. So far I can parse the MDX documents using the MDX compiler and Babel during Gatsby’s build lifecycle.

It has been such an eye-opener to realize that if we think about the README we are actually thinking about the user. Let me elaborate a little bit more about that. In the past, I’ve always had a combination of how to get the project running (deep inside with the hopes for someone to actually contribute to the project) and, how to consume the project. And that is by the way not quite right.

A lot of people will come to the README trying to figure out what exactly the project is. Our job is to explain what the project does and why it exists. Besides that, it should include all the necessary information required for the user to use the project as easy and frictionless as possible.
So, what does a README actually need? Below you will find the minimum bare bones of what the project requires:

1. Title
2. Description
3. Badges
   1. Build
   2. Test coverage
   3. npm/yarn (optional)
4. The smallest code snippet you need to start/integrate the project
5. Documentation link
6. Support channels
7. Roadmap
   1. Top feature requests
   2. Top bugs
   3. Newest bugs

The Description

Time flies by and we only have 10 minutes left in our meeting. I thought, can we please do the description together, and guess what? We did. We used the german “wer, was, wie” technique, which basically means “who, what and how”. The description should include no more than three sentences describing the project and the problem it solves in our case would be something like:

Docs is a Gatsby theme that programmatically generates visually polished and interactive technical documentation using MDX and Babel.