Lessons learned doing open source
Tags: beginners, webdev, tutorial, opensource
Published: 2020-07-16 23:07:15

---
description: An introspection on my OSS work
canonical_url: https://carlosroso.com/github-lessons-learned/
---

I'm not popular in Github but I have a [repo with 1.5K stars](https://github.com/caroso1222/notyf) and 1M hits/month. I got [some more](https://github.com/caroso1222) with a few hundred stars. Here's what I've learned along the way.

---

#### Build good looking demos

This may come off as superficial but it's worked wonders. I write frontend libraries where demos are critical for adoption. I put a lot of hours [designing](https://dribbble.com/shots/10867744-Notyf-JavaScript-Open-Source-Library) and coding [good](https://ng-popups.carlosroso.com/) [looking](https://carlosroso.com/rmind/) [demos](https://carlosroso.com/rmind/).

#### It's fine to be inconsistent

I used to [beat myself](https://github.com/caroso1222/notyf/issues/21) for being inconsistent. Not anymore. Github is [my lab](https://github.com/logo-quiz/logo-quiz), not my job. I make sure to have a stable, working version on master and move on. I come back once [motivation strikes again](https://github.com/caroso1222/notyf/graphs/contributors). I play it long term.

#### Build framework-agnostic libraries

Building [libraries for frameworks](https://github.com/caroso1222/ng-lib-schematics) is fun and it has its niche. But, if you want to have more impact, architect your libraries to be [framework-agnostic](https://github.com/caroso1222/notyf) and easy to plug anywhere (see next point).

#### Write framework-specific recipes

Whether you do backend, frontend, ML, or whatever, chances are your users are using frameworks. [Write easy-to-follow recipes](https://github.com/caroso1222/notyf/tree/master/recipes) for how to plug your library into any of these abstractions. It'll boost adoption.

#### Have a clear scope

Devs complain about clients asking too much yet we do the same on Github. You'll get a myriad of feature requests if your OSS project takes off. Communicate your scope. Learn to [oblige](https://github.com/caroso1222/ng-lib-schematics/pull/7). Learn to [decline](https://github.com/caroso1222/notyf/issues/72).

---

> *I send posts like this to +1050 devs on my email list. Join [here](https://mailchi.mp/9fbe9022e6d7/career-boost) to send you my tips and thoughts on algorithms and career growth. If email is not your thing, follow me on [Twitter](https://twitter.com/caroso1222) to get [sneak peeks of what I'm working on](https://twitter.com/caroso1222/status/1279133799222251521).*

---

#### Relaunch

I'm not a marketer so launching is always a gamble. What I've learned, though, is you must relaunch. People might have not seen your stuff the first time. Release a new version and [write a blog post](https://medium.com/hackernoon/the-last-toast-library-youll-ever-need-8629e61b8e91). [Tweet about it](https://twitter.com/caroso1222/status/1282781759105531909).

#### Sneak in to understand usage

Use the Github's [Dependency Graph](https://github.com/caroso1222/notyf/network/dependents?package_id=UGFja2FnZS0xNDQ5NDI5Nw%3D%3D) to see who's using your packages (lots of [supported ecosystems](https://docs.github.com/en/github/visualizing-repository-data-with-graphs/about-the-dependency-graph#supported-package-ecosystems)). Then visit your users' repos and analyze usage. Are they hacking it to fix a hidden bug? can you improve the API?

#### Use badges but don't oversell

[Scientific research has shown](https://cmustrudel.github.io/papers/icse18badges.pdf) that badges are positive signals for contributors and users. Adding a badge doesn't change popularity but popular projects are more likely to have badges. Use [assessment badges](https://cmustrudel.github.io/projects/badges/).

#### Use a GIF

You have just a few seconds to convince users to try your library. Put a GIF at the top of your README to help them quickly jump in. You can use [terminal screencasts](https://asciinema.org/), [GIF recordings](https://github.com/caroso1222/amazon-autocomplete/blob/master/README.md) or [screenshot sequences](https://github.com/sindresorhus/Gifski#screenshots).

#### Yes, build it again

Unless you're a seasoned OSS developer, you need to build *yet another version* of popular things. This will ignite your curiosity to try bolder things later. Don't try to code *the next big thing*. Just build something. Today.

#### Redefine success

I have [unpopular](https://github.com/caroso1222/rmind) [projects](https://github.com/caroso1222/node-reminders) with little to no installs. I'm proud of them, though. I learned a lot from building them. I use them myself. I'm getting better and [enjoying](https://logoquiz.dev/) my projects. That's my ultimate bar for success.

#### Be aware of moniker naming rules

Not sure about other ecosystems but NPM has [moniker rules](https://blog.npmjs.org/post/168978377570/new-package-moniker-rules?) for package naming. I learned it the [hard way](https://carlosroso.com/how-to-check-npm-package-availability/). Pick a good name and make sure you can work with it. Only then start coding.

---

This is a personal journal for things that have worked in my open source work. You might want to save it. I'll keep updating this as I come up with new findings. 

Do you have any advice to build good OSS projects? Let me know in the comments!

---

##### Shameful self-promotion

My mission is to help devs grow by [posting tips to write CVs](https://dev.to/caroso1222/please-stop-doing-this-in-your-resume-2mga), [teaching algorithms](https://dev.to/caroso1222/4-tricks-to-boost-up-your-algorithms-game-9bn), or talking about [my experience](https://carlosroso.com/how-i-got-into-the-most-exclusive-remote-working-platforms/) working on [top remote workplaces](https://dev.to/caroso1222/best-sites-to-land-top-remote-jobs-100k-year-4n04). I also shared my experience transitioning to [Machine Learning](https://dev.to/caroso1222/how-i-went-from-frontend-dev-to-machine-learning-engineer-6ao) and put up some [fancy illustrations](https://dev.to/caroso1222/are-these-lists-equal-28oj) to explain computer science problems. I wrote an eBook to help you land a job in [Toptal](https://www.toptal.com/#join-only-great-devs). You can [sign up here](https://carlosroso.com/cracking-the-toptal-interview/) and get it right away.