RTFM: A Story of Wasted Time

Posted on in Productivity

So a couple of days ago I changed the theme of my website or blog, more about the site update. Overall the new theme does everything I wanted. It’s clean and simple, along with the look and feel that I was going for. That being said there were some issues that I wanted to address, to truly make it perfect. These issues were with the site header and banner.

Here’s what was bugging me:

  1. The logo. I didn’t want one. I don’t HAVE one. I’m not a brand, I’m just some guy with opinions about code. Every time I try to design a logo it looks like something a 5-year-old would make after eating too many crayons.

  2. The tagline/slogan thing that appears under the site name. Again, I don’t have one of these. What would I even put? “Joe’s random thoughts that nobody asked for”? If I left it blank, the theme used its default (which I didn’t want), but if I put an empty string, the spacing went all wonky and looked like garbage.

  3. The favicon wasn’t using MY favicon from the static folder. I have this little icon I’ve used forever, and dammit, I wanted to see it in my browser tabs.

So there I was yesterday evening with this to actually do. Perfect time to “quickly” fix these issues! My brilliant plan? Fork the entire theme repository and start hacking away at the code.

Forking the repo took like 10 seconds. Finding where these things were defined in the codebase took… considerably longer. Temple files here, partials there, CSS scattered about. But hey, I found them all and made my changes! Victory!

…except now I’ve created a maintenance nightmare for myself. If the original theme author makes improvements or fixes bugs, I now have to:

  1. Pull those changes into my fork
  2. Make sure they don’t conflict with my modifications
  3. Update my site’s submodule to point to my updated fork

Who am I kidding? That’s NEVER going to happen. I’ll forget about it in two weeks, and six months from now I’ll wonder why my site is missing some cool feature that the original theme now includes.

But wait, what’s this file called “README.md”? Some kind of ancient text that contains… information?

Sigh

Turns out - and I swear this happens to me at least once a month - the theme author had ALREADY included configuration options for literally everything I wanted to change. All I needed was:

1
2
3

params:
  hideLogo: true
  hideSlogan: true

And for the favicon issue, I just needed to add properly named size variants to my static folder.

30 seconds of reading documentation would have saved me an hour of unnecessary coding. But no, I had to dive straight into the “fun” part.

This isn’t even the first time this has happened. Or the fifth. Or the tenth. I once spent an entire weekend customizing a library only to discover on Monday that there was a configuration flag that would have done exactly what I needed.

I know better. I TEACH people to read documentation first. When my junior devs come to me with problems, my first question is always “did you check the docs?” And yet here I am, a walking contradiction.

I’d like to say I’ve learned my lesson, but history suggests otherwise. My brain seems wired to jump straight to “I can fix this with code!” instead of “maybe someone already thought of this problem.”

So this post isn’t really advice for you - it’s a note to future me: PLEASE, FOR THE LOVE OF ALL THINGS HOLY, JUST READ THE DOCUMENTATION FIRST.

Next time, right? (Probably not.)

↤ Previous Post
Next Post ↦