Make the most of your project README

First, to set some context, when I'm talking about READMEs today, this is focused on a typical Laravel project, not a package. (It's not that I don't think packages should have excellent READMEs, but it's a different audience.)

When I join a project, the very first thing I do is check the project README. GitHub even makes it the default thing you see when viewing a repo. And I shed a silent tear when I see it's still the default Laravel README.

This is such a missed opportunity!

Here's are top things I want to see in a project README:

1. An overview of what this project does. Tell me a little bit about why it was created and who uses it. One paragraph is all you need, not a book.
2. List all the third-party services you integrate with. Even better, explain anything I need to set up and how to do it.
3. Provide the exact steps on how to get this project running locally. Be as detailed as you can.

There is a lot more you can include, but I find these the most helpful when getting started. If you want to see a more complete sample, we include a template in our Laravel Project Standard repo.

I admit, this tip may seem a little self-serving since I feel the pain more than the average developer due to consulting with a bunch of different companies each year.

But honestly, this simple practice will also benefit an internal team as well. Capturing that institutional knowledge is a huge asset. Don't make a new employee wait for help from an existing team member. Let them hit the ground running on day one!

And even if you're a solo dev, I think you'd benefit from a well-crafted README. It's a great way to document your thoughts and decisions as you go. Help your future (and older, more forgetful) self out!

Here to help,

Joel

P.S. Want an outsider to clone your project and make sure the README is complete enough to get started in one hour? I can help with that.