Hello Human 👋🏻

So do you want to contribute to open source? Awesome.

Does it sounds overwhelming? That's also normal.

Hacktoberfest is designed to lower somewhat the friction, but it can't possibly remove it. That's why I thought it could be useful to share some guidance on how to make simpler but more meaningful contributions.

Before we start

Keep in mind that what I propose here is my personal guidance. Some smart people will disagre. That's why they end by an asterisk*.

Actually my guidance are mostly questions in disguise. The goal is to nudge you to ask yourself better questions. If you find my solutions helpful, I'm glad. If you do the job of asking yourself better questions and come to a different solution, I am also glad. And I congratulate you.

So let's started by not speaking about programming.

Don't focus only on the technical aspects

There are plenty of good articles here on all sorts of topics like #github #hacktoberfest #typescript #beginners #html #css #react #vue #kotlin #swift #golang

The technical stuff is important but in my experience, it is not the whole picture. There is another aspect that I talked about in one of my weirdest and personal favorite article: Contributing to open-source is like dancing Tango

As I said in my post, when you take dancing lessons, there is a strange moment when the teacher say something like this:

And now, ladies and gentlemen,
please choose a partner among all those unknown people
and start dancing together very closely. 🕺🏻💃

This is inherently awkward. Some people try to work around it by dancing only with the same dancer. But there is no way around it. You have to learn to do that well.

The secret is to develop empathy.

So how do you develop empathy?

Well it took me a lot of time to work on my empathy skills until I discover a small secret:

Dance both sides of the game
Chances are that when you started a social dance like tango, you learned to be a leader if you were a man, and a follower if you were a woman. There is something magical about experiencing both perspectives that will change you. By feeling both side of the same game, you inevitably gain a much deeper understanding of the dance. It becomes also much easier to empathize with your fellow dancer.

The analogy is here obvious: you cannot really get open-source if you have only been a maintainer or only a contributor.

So that's a long term plan, but in the short term you really should focus on creating a human connection with the maintainers.

Contributing to open-source is like dancing Tango

Jean-Michel 🕵🏻‍♂️ Fayard ・ Oct 11 '19

#hacktoberfest #opensource #watercooler #motivation

Which brings me to my next point.

Don't send a Pull Request*

What? Isn't the whole point of hacktoberfest that you have to submit 4 (?) pull requests?

Well yes and no. The four PRs are a gamification trick to nudge you to learn how to contribute to Open Source. The real goal then is to become better at contributing to open source.

Now if you talk with open source maintainers, they may tell you they feel bad when a contributor comes with great intentions, and start hacking for a long time alone in his basement until the moment where the PR is finally perfect and ready!

Unfortunately it's not so simple:

• the maintainer may be overbusy with life right now, like she just got her first child
• the maintainer doesn't actually maintain the repository, because we all have more old projects than time to work on them
• the maintainer may have fixed since months the problem spent energy fixing. It was just in another branch
• the maintianer may see that there is a right idea behind your PR, but unknown to you there was a 10 times simpler solution to address it
• and just git being git and getting in the way

That's why contributing to open source can feel oh-so-frustrating sometimes. For everyone involved.

Fortunately there is an easy solution

Never start with a PR on a unknown project from unknown people.
Start by creating an issue of you explain WHY you think something deserves to be improved, and let the maintainers tell you whether that makes sense for him, and if yes guide you on HOW to do it the easy way.

Please read this again, this is really the key to make your contribution effort both simpler and more meaningful.

I can share my simplest and more meaningful contribution as an example:

Here I noticed a very small thing that could be an actually meaningful improvment. I could have sent a pull request. But I didn't.

Instead I applied the principle Start With Why

Start With Why

I am really proud of this contribution to the incredible Homebrew project. You wil see it's simple. And that's exactly my point. It's really good that it's so simple.

All started with an issue:

`brew docs` as an alias for `open https://docs.brew.sh` #13834

jmfayard posted on Sep 09, 2022

Provide a detailed description of the proposed feature

brew docs as a shortcut for open https://docs.brew.sh

Also udpate brew help

$ brew help
(....)
Further help:
  brew commands
  brew help [COMMAND]
  man brew
-  https://docs.brew.sh
+ brew docs

What is the motivation for the feature?

Laziness is one of the three great virtues of the programmer, as defined by Larry Wall.

Laziness is the quality that makes you go to great effort to reduce overall energy expenditure. It makes you write labor-saving programs that other people will find useful and document what you wrote so you don't have to answer so many questions about it.

How will the feature be relevant to at least 90% of Homebrew users?

Benefits for users

It makes it marginally easier to 90% of Homebrew users to access the docs at https://docs.brew.sh

And maybe find the information they need, which is nice.

Benefits for maintainers

It is marginally nicer for Homebrew maintainers that Homebrew users are empowered to find the documentation they need. They would have to repeat themselves marginally less.

Of course, many users still won't read the docs, but now maintainers can reply

This is documented in $ brew docs, section Common Issues

This kind of reply makes it marginally more likely that users read the docs next time. Yes it's just a RTFM, but I think/hope it's an empowering "Read the Friendly Manual" RTFM, not the "Read the Fucking Manual" RTFM.

Benefits for documentation writers

As someone who writes technical documentation myself, I know this is hard work and I know that I like it when more users actually use and benefit from the documentation.

What alternatives to the feature have been considered?

Bookmarking https://docs.brew.sh

But I'm too lazy to bookmark things and use browser bookmarks correctly.

View on GitHub

Here I didn't only reaquest a feature. I also explained very clearly my motivation for wanting this feature. Namely Lazyness, one of the great virtues.

What followed was just awesome. MikeMcQuaid, project leader of the Hombrew project immediatly replied

I love, admire and agree with the honest admission of laziness here. Given how little code would be required to implement this: would definitely review a PR.

Soon after some fellow smart people with vastly greater knowledge of Homebrew than me came up immediatly with multiple solutions. I am happy that I had shut up about the solution I had in mind. If would have created a completly different discussion.

Once this connection was established, I was more than ready to implement the PR myself. As it turned out, I didn't even have to because soon after Try MacCabe took care of it better than I could.

I'm on my MacBook pro right now and brew docs does exactly what I intended.

So what di we learn?

We learned that what matters is focus and communication.
Not the amount of efforts

Which brings me to my next, possibly contreversial, point.

Don't learn the git CLI*

Many smart people firmly believe that the git CLI is the basis of everything and you definitely should spend a considerable amount of time struggling with it and copy-pasting answers from Stack Overflow when you will inevitably mess up.

For your information, don't stress out if you git mess --up often. People with years of git experience still git mess --up things regularly.

I'm not saying that they are wrong, I'm saying that I focus on something else.

I focus on learning the concepts

What matters then is what helps people to learn the concepts and what hinders it. The accidental complexity of the GIT CLI is in my opinion a major obstacle to learning. I believe in making it easy to do the simple things and in helping to prevent developer mistakes.

Contrary to what you may think, it's not a debate of GUI vs terminal applications.
If you like the terminal I recommend to use GitHub CLI and/or lazygit
If you like GUI applications I reommend GitHub Desktop, or the IMHO awesome git integration in IntelliJ, WebStorm, PHPStorm, RubyMine, PyCharm, ...

All those git applications were designed with simplicity and usability in mind. They will help you focus on what matters most: learning the concepts.

Learn git concepts, not commands

Nico Riedmann ・ Jun 2 '19

#git #tutorial #beginners #learning

Again this is my personal advice that doesn't universally apply. If you are an hardcore C programmer working in project similar to the Linux Kernel project, specificallly Bazaar style, then the git CLI is the best possible tool for that use case, because it was designed by and for them.

Now for the really important stuff.

Help Maintainers See Things Through your Beginner Eyes

"The real voyage of discovery consists, not in seeking new landscapes, but in having new eyes." -- Marcel Proust

Looking at the codebase of an open source projects that has hundreds or thousands of commits and years of existence is very intimidating.

And you probably wonder how the hell you can do a meaningful contribution?

This is a great question, thank you myself for asking it.

As it turns out when you see things from the maintainer side, there is something that is really hard for us. We know that the first impression people have from our project matters a lot. The thing is we are bad at detecting this kind of things. We are so deep in our projects, we know so many details of it that it requires a huge empathy effort to see the project through the eyes of someone who discovers it for the first time.

As it turns out, that's something where you are much better than we are.

And you won't believe how few users will have the courage to give us this kind of feedback.

So my advice would be:

• pick an open source project that you like and where you seems to be the target audience.
• give it a try like you were a new user that want to try the project out and has only a limited time to evaluate it
• opens an issue (see before), tell the maintainers that you just tried the project, that you were impressed by xxx and yyy, and on the other hand you had some naive question about some other stuff. Would it be intersted by a detailed feedback?

If you give it a try, please tell me how this turns out.

Conclusion

I never have interesting conclusions to make and today is no different.

On the other hand, I have a request. I know that I'm supposed to share my article on social media to reach the kind of people it can help. But I'm just bad at social-media. So if you liked the article and Twitter, Reddit, ... is your thing, I would really appreciate if you can do it for me.