Your README Is Important

Good documentation is very important and expected of open-source projects.

We should hold our private projects to the same standard. The README is not a @todo. It should be available and up to date, even if only for our own benefit.

But why?

It might sound like a waste of time to document something you’ve made for yourself but you’d be mistaken.

The faintest ink is more powerful than the strongest memory.

I’ve lost count of the number of times I’ve picked up an old client’s project and been thankful I’d included a README.md. I’d taken the 5 minutes to document the setup steps, and can now onboard myself even several years later. Instead of trying to remember my workflow of years gone by, the instructions are right there.

What seems obvious now, may not be later.

Practice makes perfect

Writing concise documentation is a worthwhile skill and you should practice whenever possible. Using the documentation on your personal projects is the perfect opportunity.

This practice will benefit you and others when documenting public or team projects.

Good documentation can be the difference between a project succeeding or not. Personally, I’ll skip any project that does not have clear and concise documentation.

Hone your documentation skills and give personal projects their best chance to succeed.

Where to start?

Dig into your projects folder, find a project that is missing a README.md and get to work. Your future-self will thank you.

For tips on writing your README, refer to Eric Barnes’ great article on how to write a README that rocks.

By Mark Hesketh

I'm a PHP Developer based in UK, building modern PHP web applications and writing about everything I learn.