My Profile Photo

Iris on Tech

I'm Iris, a non-binary (they/them,she/her) electrical engineer with a passion for reverse engineering, cryptography, programming and just generally figuring out how things work. I frequently fully or partially take deep-dives into a topic of interest that isn't explained well or in detail online, and I hope to be able to document that knowledge here finally.

Brand new blog

(and a bit of a rant about setting it up)

So I have a blog now, how unique and interesting. I’ve thought about starting one seriously for a month or two now and I think it’s worthwhile to try it. You’d think it would be pretty easy to just setup a basic Jekyll site without even any theming using Github Pages, but I actually encountered a lot of headaches.

Starting the blog

What to use?

Firstly, I don’t really do web development, I’m familiar (reasonably so for someone who rarely works with it) with HTML and Javascript and CSS, but I try to stay away from them, because it ends up being a lot of fussing about with things that should work but don’t for no apparent reason. So I just went with jeykll since that’s what Github Pages supports natively these days. But I’ve never worked with Ruby (I dabbled with node.js in the past when I’ve wanted to work on little web projects, but Ruby always seemed at first like a lot to learn for one project, and then later like it was out of style and not worth learning, plus the stack seemed pretty heavy for simple little projects).

Setting up Jekyll on Github Pages

But Jekyll is pretty simple, and Github has a guide that should theoretically walk me through setting it up. So I opened up my WSL (Windows Subsystem for Linux) terminal and followed the guide. Except… it didn’t work. Firstly, Github encourages you to use a gem/program called bundler to help manage dependencies for the project/site. Okay sounds good. Normally I wouldn’t bother for something like this, since it’s so small and I’m not installing any additional dependencies anyway. But whatever, I’m a sucker for best practices and it tends to help you learn a lot more anyway. Next problem, bundler complains if you don’t already have a Gemfile, but Github doesn’t ever tell me to create one. You can solve this a few different ways, but I settled for the simplest, just using the jekyll new command directly.

The next problem is that the guide tells you that you need to use a specific version to match the version Github has on their server for deploying your site. Github tells you to use jekyll VERSION new <repo-dir>, okay version from the link they give me should be 3.8.5… Nope. Bunch of errors.

This brings me to the most frustrating part of the whole process. So I did actually solve it eventually, a Stack Overflow post had the answer (surround the version with _, ex: _VERSION_). But where is this documented I wondered?


This is documented nowhere. At least as far as my skills with Google would go in around an hour, I could not find any (official!) documentation of this feature existing. You could learn about it from either a blog post that mentions that ruby gems are wrapped in a script providing this functionality when installed (which is where I found out about it), or a number of Stack Overflow articles from people asking how to execute a command from a specific version of a gem.

This isn’t anywhere on bundler, the docs for the program that manages gems, anywhere. It’s not even clear where this is in the source code for rubygems (I think it’s in the install command handling code, but I’m not even sure). This is one of the rare times where I just stopped looking after awhile and decided it’s probably not documented. Since I was getting pages and pages of results relating to some functionality of Ruby involving underscores and variable naming.

Thoughts on documentation of software

I personally think this is a problem with Github’s documentation, with the information provided on the RubyGems website, and with just programming practice in general. It’s great to have simple, clean, targeted and cut-down documentation that serves most people’s needs. But somewhere, somehow, you have to have a verbose page that says everything. I’ve seen this with man pages for programs too. It’s nice to try to limit the amount of documentation that’s being expressed in a poor medium (say documentation better organized as a guide instead of documenting options). But somewhere the rest of it should exist.

Git (Good Example)

I think git actually does this really well. The man pages are useful, the commands all have decent descriptions (I’ve never found an option that wasn’t documentation/visable at all), and if you use -h for a specific command, you get a summary of the most relevent information. If you use –help, on most systems your browser opens the relevent web page, and if not, it opens the man page for the command, which has a full description, often with examples and guides. This means you can actually learn how to use git, simply from exploring it’s man pages (although I don’t recommend it).

JVM (Bad Example)

A bad example is something like the JVM, I recently wanted to try and manually tune the garbage collection settings for a Minecraft server I host for me and my friends. Since it runs on a fairly low-speced machine, without a lot of ram available, and recent versions of Minecraft have some performance issues. There are many, many, many, guides giving you some (likely copy and pasted) options for “ideal” settings to run for a Minecraft server. Even one from a developer I collaborated indirectly with awhile back (that one actually documents most of the options and the reasons made). However if I want to tune it myself, where do I find the documentation on the flags available and their specific impact? Basically nowhere.

I finally, finally found a page from Oracle that documented the different policies and what they do. But neither Oracle (at least in easy to find public docs) nor Amazon (the providers of the specific OpenJDK JVM build I was using) nor OpenJDK’s website provided any documentation on JVM options. They change quite frequently (due to being somewhat tied to the implementation) and could be different between the different implementations, but noone documented them. With a lot of work I could actually get the JVM to spit out the names of the options, but what to feed them (%, absolute value, etc) was completely unknown.


Why this matters

All of these problems were solved, but they took hours, over many days. As a student I had a decent amount of time where I just kind of had to wait around and I filled that time with further research, but for anyone else this is basically a huge waste of time and (potentially) money. These aren’t someone’s personal utility program on github, or a brand new project or something unmaintaned. These are well funded (at least in the JVM’s case), and widely used software applications. Prototyping the functionality you need is step one, but step 2 needs to be writing documentation, not implementing the finalized code.

Without this documentation you can’t know if a command is buggy, or designed to behave that way, and you certainly can’t learn how it was intended to be used or potential pitfalls. Even if you read the source.

Setting up Jekyll on Github Pages yourself

And if you just want to setup a Jekyll blog like me, follow the guide on github, ignore bundler. Go to Jekyll’s site and before you do anything add the environmental variables from their troubleshooting page to your .bashrc and source it. (This will make sure you can install and update your gems without sudo by setting the locations to your home directory first… why is this a troubleshooting step not a preliminary step [unless you follow the guide for NearlyFreeSpeech, which has these steps first for some reason]).

And if you’re using Ubuntu on WSL, make sure you also install libgdbm-dev and zlib1g-dev before doing gem update too because those libraries are used in some of the gem’s native extensions and they’ll just fail to update and work and then later on jeykll won’t work without a clear error…

Hope this was at least interesting, next post I have planned is also unfortunately a little bit of a ranty piece, but after that they should mostly be about projects I’m working on, emulators, thoughts on DCPU-16 era projects, struggles with choosing programming languages… etc.