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?
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
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.