Adopting a Programming Philosophy

Last year, I took it upon myself to learn the fundamentals of web development by creating a simple, static blog site using a modern web framework called Django, along with the Python programming language, HTML, and CSS. As a Computer Engineer (Electrical Engineer) by trade, I never had the educational exposure to constructing websites from scratch. Naturally, this experience proved to be a worthwhile challenge - particularly learning how to organize and style a site.

While the journey was accompanied with excitement and pleasure, I'm sad to say the end product was not. The site itself wasn't terrible. If I had to grade myself against my peers, I'd say I passed muster.

Then what was wrong with it?

I felt no desire to actually write with it.

The process for a creating a post felt clunky, disjointed, and superflously engineered. I had to remember to maintain my blog via Django's built in admin site, which managed a database via an ORM, which hopefully amalgamated various jinja styled HTML templates coupled with the appropriate css to, at last, produce a functioning site. In short, the system that I had set up for myself was a bit of a bloated mess. I had too many moving parts. Instead of actually writing, I was focused more on being a custodian.

Could I have installed additional plugins for Django to better streamline this process?

Probably.

But that wouldn't have been a sufficient answer to my problem; that was just a shift in responsibility.

Building and maintaining a static website isn't equivalent to writing a driver for a system kernel. It's a rather simple problem. Therefor, in my estimation, it should be met with a simple solution. An industrial grade framework was just overkill.

The only question that remained was how would I go about it?

Allow me to briefly veer of course on this lingering question to talk about a separate passion of mine: Handtool Woodworking. I promise, we'll return to our scheduled program.

A few years after moving into our own place, my wife and I forked over a decent chunk of cash for a coffee table from Ikea. It was, unfortunately, only after I had assembled the darn thing that I realized this expensive paperweight would not endure a lot of abuse and was ultimately destined for a landfill. You get what you pay for.

That week, with disappointment still weighing heavily on my mind, I had made the decision that the next piece of furniture we would get would not be purchased, rather built by and for the end user: me.

It was this very moment that kicked off a several year long voyage into the fascinating world of handtool woodworking. Every other weekend had become an adventure with some combination of sawdust, sweat, and iron. Despite my growing enthusiam, I started to realize that I was outmatched against the type of wood working I wanted to pursue. Having only recently graduated college, I defaulted to the primitive function of any engineer who felt outwitted and hit books. And oh, were there plenty.

Workbench design. Species of Wood. Antique Handtool Refurbishment. Treatises on Woodworking. Mechanical Excersises. A mysterious Plate 11. There was so much to grasp for someone completely outside of this craft. But I read everything I could get my eyes on. Articles, blog posts, magazines, books, and old catalogs. I couldn't discriminate.

It wasn't long after making this plunge that I stumbled upon one of the foremost writers and publishers on woodworking of our time: Christopher Schwarz. What had particularly driven me to Schwarz wasn't just his obvious knowledge on the subject of woodworking, but his philosophy on the craft itself. Within many of his published writings, Schwarz would bring up something he commonly referred to as vernacular design. But what did that mean, exactly?

Let's examine a quote from one of his articles that delve into the subject.

"It's simply not enough to look for inspiration from people who are living or recently dead. You need to reach further back in time — as far back as you can — until the trail goes cold … What will you find there? Almost always, you will find objects that were designed and made by the end user. These objects, which are sometimes called 'vernacular', are almost entirely utilitarian." ~ Christopher Schwarz, The-Mostly-Forgotten-Power-of-Vernacular-Design

There are many passages in his other published works which go into further detail to harness this idea of vernacular design, but as I ingested more information I began to detect regular patterns in his descriptions. Words such as utility, practical, simple, and tradition were vital to the definition of it.

I believe after years of consolidating these principles of vernacular design, Christopher Schwarz was able to successfuly adopt it within his own work as a craftsman; and it shows. For those interested, I'll leave a link to his portfolio.

But was vernacular design strictly bound to fields of study such as architecture, woodoworking, and culture? If Schwarz was able to successfuly apply these principles to his craft, why couldn't I apply it to my own?

At its core, I believe vernacular design is an adoption of the pragmatic. But if someone wanted a foundation for applying it, where would they start?

The following rules should in no way be described as definitive or invioble. But I think for the remainder of our discussion, they will serve as a starting point.

It would be an incredible disservice if I set out to define a programming philosophy and didn't attempt to apply it. So what better of a test than to try to answer the lingering question regarding my static site? We're now back to our original program.

To recap, I wanted to have a better process for creating and maintaining my static site - something that was simpler and easier to understand. Below is an attempt to apply the some of these principles to come to a conclusion. It's important to note that application is never perfect, the important thing is to try to stick to these principles.

Requirements:

• The primary function is to gather blog posts and other related files to be published to a static site
• The system should be easy to maintain
• The solution should avoid incorporating avoid complex and closed-source frameworks
• The inputs for the site should use an easily workable format like text files or markdown
• The solution should be a well tested with a good track record

To my initial surprise, there were actually quite a few very capable tools out there which fit most of the requirements I had in mind. From Obsidian.md, a popular markdown note taking app which is now capable of publishing sites (via a subscription), to frameworks like Hugo and Jekyll which are relatively lightweight static site generators that have attracted a lot of attention. However, there was one tool that remained the most attractive based on the level of control it provided, its ultimate simplicity, and it's battle tested credentials.

Recently I decided to switch my primary text editor back to GNU Emacs after a rather long hiatus. The primary reason for this decision was one of the major modes that comes native with the tool: Org Mode. To be brief, Org Mode allows users to write plain text files which can be leveraged to organize notes, manage tasks, write computational documents, and so much more. Both Emacs and Org Mode have been around for decades. Despite their age, they have maintained their relevance through active communities of users and developers.

While reacquainting myself with Emacs and Org Mode, I discovered a very powerful feature that allows users to export a collection of org files (a text file recognized by Org Mode persisted with a .org extension) into a static site. This was precisly what I needed per the requirements previously established; a native capability within my preferred text editor to organize plain text notes into my very own personal site.

Now, I would be incredibly remiss if I didn't mention the initial growing pains someone will encounter while trying to configure Emacs and Org mode to perform the task at hand. Emacs, afterall, is written in a language called Elisp, a dialect of the Lisp programming language which has been around since the 1950's. I'll have to write several blog posts on my exploration of this intriguing language, but suffice it to say that, for now, there are resources available to assist in the production of what I perceived as an acceptable end product.

After a few days of tinkering and learning the process, I was able to achieve nearly everything that I wanted within a meager elisp script that sits under 150 lines of code. Pretty impressive.

In keeping faith to the principles of vernacular design, I opted to use a simple GNU Makefile for handling the build process. There are other efficiencies that can be made, but we can get to that later.

What is incredibly satisfying to me is that this entire project can be housed in a modern source code management platform, such as GitLab, and with a simple CI/CD pipeline script I can orchestrate and automate builds using nothing but plain text and the git command line tool.

Overall, I'm not only pleased with how the site turned out, but perhaps more importantly the process by which I maintain and scale it. While newer tools and frameworks afford developers and users the ability to kickstart their projects with relative ease, they often lack the level of control that allows someone like myself to leverage the simplicity of vernacular design principles. All that is left for me to do is actually commit to this passion of mine called writing.

Cheers.