It’s 1 am, I’m unable to sleep and have all these crazy ideas running through my head. As I start to doze, I have a spark of genius. I think to myself this would be an awesome open source package. I guarantee others would love this. It’s so useful why hasn’t anyone else thought of it.

Over the next two weeks I spend hours and hours thinking, building, refactoring, and creating this package. I think it’s going to be the best ever. Seriously it has to be, it’s so useful.

I’m finally ready to release it. I spend at least an hour crafting the best tweet I can. Secretly wishing it will go viral, hoping others will love it, and just from one single tweet Hacker News will have it featured all day. It’s time! I hit “tweet”, sit back, and watch in great anticipation.

After the first five minutes nothing happens. Sure, some friends retweet it but it’s not gaining momentum. So now I think I’ll just wait till tomorrow when more people have seen it. But still nothing.

Where did I go wrong? Was this a dumb idea? Why doesn’t anyone like it? Is the code horrible and no one told me?

As software developers we tend to look at things from our own perspective. Assuming everyone else will see it the same way. I’ve spent all this time developing but I didn’t take those extra few minutes to really polish the marketing text. This is the big mistake. I know you are thinking it’s open source, do I really need marketing? Without a doubt yes you do!

Your readme is the first page people see when they find your package. It’s important to clearly define what the package does. List out benefits not features. Features are important but only after you’ve sold me. I need a quick overview of why your package is going to make my life easier.

The fact is you have very little time to sell someone and people do not read. They glance. If nothing stands out, they move along faster than a cheetah chasing a gazelle.

I’ve seen it time and time again where I find something that sounds cool only to have this be their main section of the readme:

Includes awesome package

Uses x design pattern

BDD, DDD, TDD

And on and on.

What does that tell me? Nothing. I really don’t care about this. Instead show me the benefits. Show or tell me why my coding life is horrible without your package.

Here are a few packages I found that I believe excel with this:

Intervention Image

Look at the demo code which is the first thing you see:

// open an image file $img = Image::make('public/foo.jpg'); // now you are able to resize the instance $img->resize(320, 240); // and insert a watermark for example $img->insert('public/watermark.png'); // finally we save the image as a new image $img->save('public/bar.jpg');

I think to myself. WOW. That’s all it takes to upload and resize an image? I’m using this!

Carbon

Both Carbon and Intervention use the same style by letting the code speak for itself. Here is a portion of their main page:

printf("Right now is %s", Carbon::now()->toDateTimeString()); printf("Right now in Vancouver is %s", Carbon::now('America/Vancouver')); $tomorrow = Carbon::now()->addDay();

Dispatcher

Dispatcher is a package for scheduling tasks inside Laravel:

Notice how these packages explain and demonstrate why I would want to use them. It’s really that simple!

Take the extra 30 minutes and ensure your readme is clear, precise, and tells me why I should care. Be specific. Sell the benefits. Take a screen shot. Wow me.