5 Simple options for improving your open-source package

It always boggles my mind when smart developers pour hours and hours of their brilliant experience into coding an open-source package, and then they completely drop the ball when it comes to the delivery. From omitting installation instructions to the briefest of descriptions, packages that would otherwise be usable are instead dumped as veritable charity cases onto the unsuspecting community. Only the most amazing packages survive these types of lapses, so don’t let your hard work go to waste by failing to do these simple things!

1. Include a README. Everyone who knows me knows that I am passionate about writing good documentation, and really, there’s no excuse for the unforgivable self-own of omitting a README file. In a few words tell us what language(s) the package is written in, what it does and who it’s for. Remember from history class learning how Western civilization was set back a thousand years when the Library at Alexandria burned? Our software civilization is being needlessly decimated by all the missing README’s.
2. Include a good description for the package manager. This could be in the package.json for NPM packages, the composer.json for PHP packages, or the mix.exs for Elixir packages. You can even copy and paste lines from your README, just please, include a description! This is how users will find your package, so make sure it includes relevant search terms.
3. Add documentation. This can simply be examples demonstrating how users can use the functions in the package. In Elixir, where documentation is built into the language, omitting this is a jaw-dropping mistake that says “I don’t know what I’m doing.” Your package should be a nice resumé piece that speaks to your attention to detail, so don’t scrimp on it!
4. Shields Up! These little icons can tell users everything from the percentage of code covered by tests to the number of downloads to the date of the last update. Browse through https://shields.io/ and you will find several shields that catch your eye. You can look over the source code of one of your favorite packages and see how they generated the shield icons for their software. It doesn’t take much time to add this little bit of professionalism.
5. Got Logo? Not every package manager supports having a logo, but some do, and you can make your package recognizable. I am fond of The Noun Project: with proper image attribution, you may freely use small logo-sized images for your open-source projects.

I wrote this article with Elixir packages in mind, but these points are relevant to any language.

Happy coding!