Positioning + Your ReadMe

I recently did a talk at Fosdem about project websites that don’t suck, because 1) a website homepage is the most publicly visible manifestation of your project, product and company’s positioning and 2) an astounding number of projects and companies do not have good websites.

But today I wanted to talk briefly about ReadMes. If we are just talking about the project, I see the ReadMe as the homepage equivalent. It has many of the same goals as a homepage:

  • Explain clearly what the project is

  • Explain the outcomes someone can expect from using the project

  • Help people understand how the project is different from other projects (or commercial products!) in the ecosystem

And ultimately, help people make a better choice about whether or not the project is a good fit for their use case.

Pay attention to your readme and treat it with the same care as your website homepage. The format is going to be the same, but much of the information is the same.

Oh, and yes you’ll want to tell people how to get started, too. But the key is that you start with why they would want to get started, and then tell them how to do it.

Poor project ReadMes are a big issue in open source. If you’re building a company around your project, you’ve got no excuse for having a ReadMe that sucks.

###

Other news!

I’ve been slacking on the newsletter because I’ve been very busy with Open Source Founders Summit! If you’re the founder or in a leadership role at an open source company, you should join us this May 27th and 28th in Paris! We’ve sold all of our early bird tickets, but if you buy tickets before midnight CET on Friday the 15th, you can use the code O5F5FRIENDS to get 20% off the full price tickets.

Also, next week is KubeCon EU in Paris! If you’ll be there, reach out so we can meet in person.

Emily Omier