Writing About Thinking About Writing

Over the weekend I had a realisation. For years I’ve had the best intentions of keeping a blog, but I never actually wrote it.

Since this website went live several years back, its been rebuilt half a dozen times, from WordPress, to Symphony CMS, to Jekyll, back to WordPress and so on. I’ve been a freelancer, a contractor, and now a full-time employee. I’ve switched disciplines from designer, to front-end developer, to back-end developer. My workflow has progressed from MAMP to Docker, Dreamweaver to PhpStorm, WordPress to Laravel and jQuery to React.

In all that time I’ve written very little. Plenty of drafts but rarely published. I look back at the techniques, tools and technologies I’ve learnt and wish I’d posted more.┬áRather than write, I’d start a new project, re-build this website, learn a new tool.

I meant to write about it, I just didn’t.

Posts published in 2017: 1 (one). Good stuff.

I’m changing that. No, really this time! Honest. I’m going to start writing without pressure or expectation. I’m going to blog like its 2005.

Adam Wathan, a developer I follow in the PHP community, recently tweeted
that he has been using Basecamp’s ‘Automatic Check-in’ feature to keep a work journal and keep himself focused. Its a technique Jeffrey Zeldman has also written about. I plan to do this too, but in public on this blog.

Future projects I’m working on, such as the ambitious Laravel-based e-commerce store I’m planning, I will write about. Any techniques I come across along the way, I’ll write about them too. I’ll write as much as possible for my own benefit and if others find these posts helpful then even better!

In the mean time, this is me writing about writing, but I’m happy to actually be doing it.

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.