Kevin Macksamie

I used Nix flakes to customize the version of Hugo for a development shell. I didn’t realize I was going to have to override Nix’s built-in buildGoModule function.

Exploring Nix is intimidating for a newcomer. It’s a language, an ecosystem, a platform, and a philosophy, but it’s also kind of fractured between classic Nix and Nix flakes. Here’s my short account of using nix-shell and nix shell to create a development environment to build this blog.

There has to be a better way to manage the state of a computer, right? Is NixOS it? I don’t know yet, but it can’t be any worse than what I’m doing now, right?

Software projects need to have good documentation. This makes the software more approachable and impacts its users and contributors. More importantly, it increases the software’s signal-to-noise ratio, allowing developers to better understand if the software meets their needs. This is not revolutionary: high-level software developed today (i.e., using the C programming language or above) presumably uses third-party code, open-source or not. Writing software documentation, however, is challenging and thoughtful work. This is the reason why technology companies hire technical writers and developer advocates: they know good documentation is critical for their product.

Markup languages, such as Markdown and AsciiDoc, have become essential in developing software documentation. Their similarity to programming, with toolchains and a lightweight syntax, aligns with the developer mindset more so than traditional word processors. Documents written in them have a low barrier to read (e.g., you need only a text viewer installed, like more) and easy to read diffs, making their history easy to track using a version control system.

Like software source code, markup languages allow authors to write the same content a thousand different ways. With this type of flexibility and creativity in the documentation process, it helps to employ techniques to make writing documentation as enjoyable as writing code and to make the documentation source files as aesthetically pleasing, consistent, and efficient as well-styled source code. This post shares four such techniques that have improved my writing experience.

Application programming interfaces (APIs) can get whacky, but compiled languages help users to get things semantically correct. And dynamic languages? Their ergonomic “dynamic sauce” ladled over a codebase can sometimes be less than helpful. This post is about how Groovy’s @CompileStatic can help to demystify what is happening at the call site of a method that has the same name and descriptor as another.

I recently had to develop a Java client to interface with an internal service over HTTPS that required client certificate authentication. It is not often that I need to dive into SSL certificates, and doing so usually requires me to step back and relearn some things. This situation was no different, but in an attempt to burn this stuff into my brain, I am writing about it here.

Hugo has not been the most intuitive thing for me to configure. I have spent more time than I would like reading Beautiful Hugo’s layouts to understand why the pages look the way they do. However, this is the point of what I am doing here: learning, writing, and sharing.