DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’»

DEV Community πŸ‘©β€πŸ’»πŸ‘¨β€πŸ’» is a community of 967,611 amazing developers

We're a place where coders share, stay up-to-date and grow their careers.

Create account Log in
Cover image for Can beginners make a simple but meaningful contribution? Some unconventional advice #hacktoberfest

Can beginners make a simple but meaningful contribution? Some unconventional advice #hacktoberfest

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.

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

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
Enter fullscreen mode Exit fullscreen mode

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.

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.

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.

Top comments (22)

Collapse
 
jarrodhroberson profile image
Jarrod Roberson

Lots of good information in there!

I would like to add a couple things.

  1. Sublime Merge is the best graphical Git client available.
    I am one of those CLI is the canonical way to do Git. This tool has almost completely supplanted my use of the Git CLI for batch processing of Git tasks. I still use the CLI when I am in the terminal and for more advanced Git voodoo incantations. It is way better for doing things that would require more than two or three commands via the CLI.

  2. Writing test cases is a great way to gain the trust of a repository maintainer or project community.
    Writing tests that are missing is a great way to learn a code base. It is a low risk way to send pull requests and gain the maintainers trust and show you know how to follow the projects coding guidelines and write correct useful code. It is also grunt work that no one wants to do and will gain you exposure to the community.

Collapse
 
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄ Author

Thanks, I wanted to write about tests but I forgot.

Collapse
 
jarrodhroberson profile image
Jarrod Roberson • Edited on

You covered a lot of cases, great information, that is the only one that I could think of that might be worthy of mentioning including.

Collapse
 
maddes profile image
Daniel Scholtus

LOL, pretty much the typical PR...

I wanted to write about tests but I forgot.

Thread Thread
 
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄ Author

Yep, this is why you can do it the other way around. You submit just the test case to help the maintainer see what you have in mind, but not one bit of the implementation. That would be waste at that point. Wait for the feedback on the design and only after that work on the implementation.

Collapse
 
balastrong profile image
Leonardo Montini • Edited on

Great article, also thank you for moving away the spotlight from technical stuff.

A blocker I'm noticing on developers at their first approach to Open Source is that they don't "feel ready", often overwhelmed by large repositories.
Creating an issue first on what you'd like to do is an amazing suggestion as like you said it can creates the bond between contributor and maintainers... and they can give you some advice!

Collapse
 
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄ Author

Well said, I completely agree.
They don't realize how valuable it is to just say "hey I just tried your software for 20 minutes and here is what I struggle with"

Collapse
 
darkwiiplayer profile image
π’Š©Wii πŸ’–πŸ’›πŸ’šπŸ’™πŸ’œπŸ’πŸ’Ÿ

πŸ¦„

Collapse
 
lico profile image
SeongKuk Han

I'm really impressed. 'Why' and 'Empathy'...
That makes me think around back myself. Thanks for the article, bro.

Collapse
 
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄ Author

You are welcome!

To be honest reading is not enough though. Maybe I'm just saying nonsense. Maybe it only applies to me.

The only way to know is to try something out yourself.

Collapse
 
leob profile image
leob

Wisdom!

Collapse
 
renancferro profile image
Renan Ferro • Edited on

It's my first Hacktober and I'm really excited! If it's someone's first time too, let's talk and help each other! And thanks for the article, it helped me a lot!

Collapse
 
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄ Author

Great to hear.
Already found a project?
Which tactic do you want to try first?

Collapse
 
incrementis profile image
Akin C.

Hello Jean Michel Fayard,

thank you for your article.
I love how you help beginners with this article.
In my opinion, empathy is a soft skill and is greatly underestimated in technology.
I would add that patience is also important when communicating with people in tech.
The existence of a culture of error tolerance is essential.

Collapse
 
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄ Author • Edited on

I agree with everything except the term "soft skill".

What does it mean "soft" skill?

If it means skill for "soft"ware developers can benefit from, hell yes.
If it means it's easier than learning C/C++, hell no.
In fact I know many people can become good at programming in 3 years but good at whose women skills in 3 decades.

Maybe we can simply say that those are valuable skills to have in your toolbox?

Collapse
 
incrementis profile image
Akin C.

"What does it mean "soft" skill?"

Thanks for the question.
I found a suitable and easy to understand explanation on Wikipedia:

"Soft skills, also known as power skills, common skills or core skills, are skills applicable to all professions.These include critical thinking, problem solving, public speaking, professional writing, teamwork, digital literacy, leadership, professional attitude, work ethic, career management and intercultural fluency. This is in contrast to hard skills, which are specific to individual professions."

In short, this part of your comment I think sums it up best:
"If it means skill for "soft"ware developers can benefit from, hell yes."

Thread Thread
 
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄ Author • Edited on

The list is right.

I was thinking about the arbitrary name ("soft skills") that some consultants in human resources in English speaking countries decided to use.

Let see an other arbitrary name.

Le savoir-Γͺtre est un ensemble de qualitΓ©s personnelles, d'habiletΓ©s sociales correspondant Γ  la capacitΓ© de produire des actions et des rΓ©actions adaptΓ©es Γ  l'environnement humain et Γ©cologique. Il est nΓ©cessaire Γ  l'autonomie, au partage avec les autres et Γ  une vie vie affective riche. _

That means something like knowing how to exist in the world.
Holy shit that seems not so soft anymore.

What do the italians say?

La competenza sociale Γ¨ la competenza psicologica, relazionale e comunicativa, legata all'adeguata comprensione ed utilizzo, da un punto di vista cognitivo, affettivo e funzionale, delle regole di interazione sociale.

Ah yes I can see why being competent socially can help you when you interact with strangers on GitHub.

And I'm not very surprised that Italians see this as important.

What about English?

Well there are alternative names in your definition

"Soft skills, also known as power skills, common skills or core skills, are skills applicable to all professions."

Power skill does seem more powerful to me!

This is in contrast to hard skills, which are specific to individual professions.

So you could choose a different word here and say that knowing the internals of C++ is a specific skill (instead of hard) that is useful to much less people.

Isn't it interesting that if you choose different words you are less surprised that empathy, listening, communication etc... are actually very important?

Thread Thread
 
incrementis profile image
Akin C.

"Isn't it interesting that if you choose different words you are less surprised that empathy, listening, communication etc... are actually very important?"

I agree that using different wording can have different effects. Your first comment is a good example imo.

And I also agree that regardless of the naming (soft skill or power skill), the importance of the topic should be eminently present.

Collapse
 
fabestah profile image
fabestah

Thanks for your article, it was quite an interesting read for me as a beginner :D
I will definitely apply some of your stated advices, especially the ones about asking maintainers before opening PRs and providing maintainer information about what my perspective on the project is.

Additionally, I have found some typos and grammatical mistakes in your article, so I thought I would list them for you here (only a suggestion, don't want to make you look bad):

If would have created a completly different discussion.

β†’ "I would have ..."

So what di we learn?

β†’ "... did we learn?"

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

β†’ "... possibly controversial, ..."

If you like the terminal I recommend to use GitHub CLI and/or lazygit

β†’ "... and/or lazygit." (missing dot)

pick an open source project that you like and where you seems to be the target audience.

β†’ "... where you seem to ..."

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

β†’ "... user that wants to ..." & "... time to evaluate it." (missing dot)

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

β†’ "open an issue ..."

Would it be intersted by a detailed feedback?

β†’ I don't quite know what you initially wanted to phrase in this sentence.

Collapse
 
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄ Author

Hello thanks but I let some errors on purpose. Perfectionism is a poison

Collapse
 
fabestah profile image
fabestah

Well, regarding programming for sure but apart from that, I guess it lies in the eye of the beholder 😜

Thread Thread
 
jmfayard profile image
Jean-Michel Fayard πŸ‡«πŸ‡·πŸ‡©πŸ‡ͺπŸ‡¬πŸ‡§πŸ‡ͺπŸ‡ΈπŸ‡¨πŸ‡΄ Author

β€œPerfectionism is the voice of the oppressor, the enemy of the people. It will keep you cramped and insane your whole life.”
themarginalian.org/2013/11/22/bird...

🌚 Friends don't let friends browse without dark mode.

Sorry, it's true.