The Shoemaker's Children: A Developer Allegory

It was a simple plan: give my personal website a makeover and write a blog post about the process.

I had built my website shortly after learning about UI frameworks, and while my Bulma-based site was nicer than some, I wasn’t in love with it. Here's the "before" picture:

Additionally, I’m a bit embarrassed to admit that despite my love of CI/CD, the “release” process for my personal page was to ssh into a server and perform a git pull. Not exactly state-of-the-art.

I started researching static-site frameworks, and thought maybe I would use Gatsby to build my site and deploy it with Netlify. With Gatsby I could even blog directly on my own site! Surely this was the modern, best-practice way to develop my page. Then I read this post by @flexdinesh , and my plans came crashing down. His post showed off an elegant developer landing page that he open-sourced, along with instructions on hosting it on GitHub pages. I was initially reluctant to use his project, because I felt like I should build my own page, but ultimately I realized that it did exactly what I needed and would help me craft a much more interesting post than “here’s how I built my website”. So I present to you: A Developer Allegory.

If you’re not familiar with "the shoemaker's children go barefoot", it’s an expression meaning that people often forget professional expertise in their personal lives. This was certainly the case with my personal website - I was neglecting development best-practices left and right. The four that I’m going to talk about in this post are:

• Continuous Deployment (CD)
• Keep It Simple, Stupid (KISS)
• "Not Invented Here" Syndrome (NIH)
• Don’t Repeat Yourself (DRY)

Continuous Deployment

In continuous deployment, a suite of tests is run every time you commit code to your project’s master branch. If all tests pass, the new build gets deployed. This allows you to get feedback on changes very quickly, and makes releasing code (which is often a risky endeavor) a non-event. There are many ways to add CD to a project, including Travis, Circle, Jenkins, and Netlify.

As mentioned above, one of the reasons I wanted to redo my website in the first place was to improve my “release process”. There were a couple of problems with my old process. The first problem was that it was cumbersome: each time I committed changes to my GitHub repository, I had to perform extra steps to get those changes into my “production environment”. The second problem is that those extra steps included a git pull, which can have unintended consequences as documented here. I wanted to install a continuous deployment pipeline to make the process simpler and less error prone.

Keep It Simple, Stupid

While Netlify (and the other CI/CD pipeline tools) could certainly handle my simple static-site requirements, they were overkill. I don’t have a test suite to run, and I don’t have complex assets or a build process. I just needed my code changes to be reflected on my website, which, as I learned from @flexdinesh 's post, is precisely what GitHub pages does.

Somewhat mean-spirited in phrasing, KISS (Keep It Simple, Stupid) implores us to avoid complexity. It also shows up in extreme programming as YAGNI (You Aren’t Gonna Need It) and in design via a quote from Antoine de Saint Exupéry: “perfection is finally attained not when there is no longer anything to add, but when there is no longer anything to take away”. By keeping code, processes, and UI simple, there are fewer places for bugs to hide, and fewer sources of confusion for users and developers alike.

"Not Invented Here" Syndrome

I was excited to learn about GitHub pages when I first saw @flexdinesh ’s post, and I thought his landing page looked fantastic. Despite that, I made excuses for why I couldn’t use his framework: it won’t be easy to list and link to my projects, I won’t be able to incorporate a blog, there’s nowhere for me to put info about myself, my “how I built a portfolio website” blog post will be redundant with his. I was exhibiting "Not Invented Here" Syndrome.

There can be many reasons for this reluctance to use an existing external implementation: cost, pride, fear of the unknown. However, NIH is completely counter to Open Source culture. In Open Source, rather than forcing each developer or team to reinvent the wheel, we can build off of each other's solutions, and ultimately create something greater than any of us could have managed alone. Once I recognized NIH in myself, I was able to fight against it.

Don’t Repeat Yourself

With Dinesh’s project, I abandoned my plans to publish blog posts on my site, showcase specific projects and apps that I had worked on, and list qualifications and career experience there. The more I thought about that, the more sense it made. I already have dev.to for blog posts, GitHub to showcase my projects, and LinkedIn and a resume to list qualifications and career experience. Why should I duplicate all of that on my website, requiring me to make updates in multiple places whenever any of these changed? I also learned that GitHub allows you to choose which projects you want to showcase on your GitHub profile ("customize your pinned repositories"), which sealed the deal for me.

This realization that I had been duplicating information reminded me of the DRY principle in programming. DRY eliminates the need to perform a single update in multiple places, which saves time and prevents errors. Of course, DRY can be (and, in my experience, often is) taken too far. To remove repeated code, developers often create an abstraction layer, but if the repetition was more coincidence than equivalence, this can be dangerous. You can read more in Sandi Metz's post duplication is far cheaper than the wrong abstraction.

Wrap Up

I'm very pleased with the final product, also viewable at www.joncass.com:

As in the shoemaker’s children aphorism, my personal projects often don’t get the love and rigor that I apply at work. While that’s fine for some projects, especially early on when I may not continue with them, I wanted my “web presence” site to have a little extra care put into it. I’m more likely to keep it updated if it’s easy to do so (thanks CD!). I think my new simple (shout-out to KISS) and uncluttered (nice and DRY) page lets me put my best foot forward on the web, even if it was Not Invented Here :).

Questions or comments? Leave them below!

A big thanks to @flexdinesh for open-sourcing his dev-landing-page project (and writing about it).