Software Development Ergonomics and RSI

Published: February 23, 2023, updated: January 4, 2025

Some rather intense keyboard clacking over the past years has resulted in me having to give my hands some time off work.

As a software developer, I pride myself on being able to develop complex systems from scratch. I can analyze the problem, choose the right tools, and design and develop solutions. I can maintain and grow the implementation as the business grows over a long period.

The right tool

Choosing the right tools can mean a lot of things here. Some of the criteria I use for selecting frameworks and libraries often I call the tool criteria:

  1. Is it easy to solve my problem using this tool?
  2. How easy is it to get started with it?
  3. Does the tool grow with my app, and as that app becomes more complex, does the tool still provide answers?
  4. How large is the ecosystem and community, what does it integrate with, and do I get answers to my questions?
  5. What is the quality of documentation?
  6. Are there escape hatches when I need to add something I make myself?
  7. Are there a lot of companies solving similar problems using this?

Django

An example of a good tool that solves my problems in web app development is Django, appealing to many points in my tool criteria Django boasts being able to solve a wide variety of problems that developers typically encounter throughout the lifecycle of app development, ranging wide into topics like security, scalability, and extendability. The Django tutorial gives a good overview of what Django can do and how to get started. And, as my applications written in Django grow over time, I can pick from many ready-made libraries that help me solve my problems.

The Django community is big, there are annual conferences, and a quick look at Stack Overflow reveals hundreds of thousands of answers to problems that developers have encountered so far. The documentation is superb, and for any detailed questions, the source code itself is well-structured and legible.

When I encountered problems that required a custom approach, I was always able to write libraries to fix these issues quickly. And many companies could grow their products using Django, even if nowadays they use a wide variety of frameworks and libraries to continue their development. Instagram and Pinterest are prominent examples of companies using Django, which is confidence-inspiring.

Since I believe in the importance of enjoyment in my work, I think a lot about whether using something is fun. Fun can be many things, be it an innovative approach to solving a problem or easy debug-ability when encountering problems. Of course, I would rather have it so that I don’t experience issues in the first place. Complicated problems require me to dive into hour-long debugging sessions.

Going in the wrong direction

Then, unfortunately, comes the darker side of why we choose the things we use. We choose tools because they look cool, are hip, increase someone’s clout, and so on. Many say they choose tools based on their technical merit, but even I am often guilty of using something simply because of the number of upvotes it has received on Hacker News.

Making fun of non-relational databases has become a favorite pastime for some. Not to mention the successor of Google’s Borg: a tool many accuse of being the result of a top-down decision in favor of being able to scale their product for a future that is far away indeed.

Ergonomics

When you choose something that falls short of some of the tool criteria, one of the things that always suffers is ergonomics. Ergonomics can mean a lot of things, but I often encounter issues with the following:

Here is where it went wrong for me at the end of 2022: my website and blog broke terribly. I have spent a few weeks migrating my site from Jekyll to Hakyll. Hakyll drew me in because it allows you to pandoc more directly without endlessly spawning pandoc processes inside Jekyll, which was slow in comparison.

In the beginning, it worked well. Hakyll uses Haskell, and it has you effectively write your site generator instead of Jekyll’s path and configuration-driven approach, with some light plugin writing here and there.

Being able to write a fully static site generator meant that I was able to dive deep into pandoc and write markdown filters for Graphviz and MscGen based diagrams.

That felt so elegant and I was pleased. And Haskell having a sophisticated typing system means that your website could be correct by construction. Building skills in Haskell programming builds transferable skills for working with other programming languages. My website is going to be robust, and I can learn a lot.

Using pandoc and XeLaTeX allows me to generate PDF versions of my articles, and with Graphviz and MscGen, I could generate SVG for the web and EPS for PDF. It sounded elegant. I am familiar with TeX from my university days, so this aura of formal correctness has always appealed to me.

The price I had to pay turned out to be enormous. First, wrangling with the type system took a lot of work. And as time passed and transient dependencies got updated, it became increasingly frustrating. Part of it might also have been my lack of familiarity with Stack–the Haskell build tool and package manager.

Until this day, I don’t fully understand how exactly GHC, Cabal, and Stack divide their roles and how they interact with each other. There’s always another page of documentation that you can read to further your understanding of these concepts. But at some point, you want to get on with it and start writing blog posts.

Upgrading to M2

At the end of 2022, I was trying to get my site to build again on my M2 MacBook Air. Before, I would run the site generator on my x86 Debian machine or an old and clunky 2013 MacBook Air. The compile times have always been maddeningly slow on that 2013 MacBook Air, as Stack insists on compiling hundreds of modules from scratch, which is a surprising amount for a static site generator.

A tool that essentially has to write some HTML files, and then you FTP them onto your web server. And yes, there are a lot of features in a static site generator, like asset minification, sitemap generation, RSS feeds, i18n, and so on.

Hakyll didn’t even have these features out of the box, meaning I would have had to write them from scratch, use a library/follow someone’s tutorial, and then discover it doesn’t work for my particular use case.

The final straw was realizing that to compile my static site generator written in Hakyll on my M2, I would have to switch to a much newer version of Stack than the one I used on my previous systems. That version of Stack would pull in a new Hakyll and pandoc. A lot of pandoc’s API has changed in minute ways. And, since the resulting number of necessary changes in my codebase was so large, I faced a lot of work.

Seeing the Haskell compiler giving you an endless to-do list in the form of tens of new type errors is frustrating. Each type error requires you to dig into the Hakyll and pandoc documentation and, even worse, through library code. Given my intermediate Haskell skills, reading library code would often be challenging, as it constantly uses advanced Haskell typing concepts.

For some reason, my particular configuration of Stack refused to accept overloadable Haskell strings, so in every location where the compiler would morph strings into the correct form for me, I would now have to manually adjust them and pass them into the appropriate type wrangling functions myself.

Why does something that has worked so well before punish me so hard by breaking exactly when I need it just because I update the environment? Yes, I am using these projects free of charge, and countless people volunteer their precious time to maintain them. And I appreciate the amount of work I have been able to do so far using these tools.

At some point, though, I need to move on.

RSI

Repetitive strain injury, or RSI, is a group of injuries that affect the skeletal and nervous systems and can manifest in many ways that I do not feel qualified to discuss. If you have any issues while you use your computer or other work tools, it doesn’t hurt to get it checked out sooner rather than later.

In my case, I have had over-sensitized nerves in my right hand’s fingertips. Copious amounts of typing caused this on keyboards that are too hard and with a typing intensity that is not sustainable for long periods. The amount of strain made typing an unpleasant experience. Not long after, I would judge any minuscule code I had to write with a “Do I want to inflict pain on myself this time to get it done?”

The cure, as with many hand injuries, among others, is rest and plenty of rest. That means I have to type much less, predominantly with my left hand. Automatically, that influences how I choose tools for the coming rehabilitation. I want to use something that requires considerably fewer keystrokes, allowing me to rest more and still giving me the feeling that I am achieving something. In this case, development ergonomics means: is working with this tool going to lay waste on my body?

Hugo

Writing a blog post itself takes a few hours. By the time I could superficially fix most of the issues, I must have been working on it for hours already. And realizing it’s nighttime and not having written the blog post itself because your static site generator keeps breaking is demotivating and heartbreaking. As someone who thinks of himself as an able developer, not being able to turn a Markdown file into an HTML file effectively is a humiliating experience.

I have used Hugo effectively for my corporate website. Since it’s a small site, I can only judge to some extent whether Hugo grows with the scope of the project. Reading again through the Hugo documentation recently, I learn that Hugo has it all:

That gives me hope that Hugo can grow together with the project.

I decided to give Hugo a spin. And in the beginning, the resistance I felt was high. How do I use Graphviz? How do I generate PDFs? But isn’t it written in Go? And again, I thought long and hard and realized: my blog has 4 or 5 diagrams made in Graphviz. And yet, I must have spent two days implementing the Graphviz feature. I suspect no one ever reads the PDFs, yet I have spent a long time trying to get CJK fonts to work well and ensure that embedded figures render alright.

Go, the language used to create Hugo feels clunky to me, but who cares? I don’t need to work with Go myself. Hugo works well for me, and as I slowly tried porting my site to use Hugo, I was swallowing my pride bit by bit, and in the end, I arrived at a new build that works well enough in Hugo.

“Well enough” is the criterion I should use more often to understand whether something works for me. Well enough means that while I might not be able to do everything I want (like easily integrating external tools), I can still achieve 90 % of what I need to achieve. And in the end, all I want is to publish some Markdown on my website and move on with my life. The goal is to communicate my ideas and thoughts with other people over the internet.

I’m not in the business of reinventing web publishing. And for the foreseeable future, every time inspiration hits me, I can jump into a text editor and promptly publish it to a broad audience anytime I want to, without a hitch.

Tags

I would be thrilled to hear from you! Please share your thoughts and ideas with me via email.

Back to Index