Posted On: 2019-08-26
I don't often write about it, but in addition to game development tasks, I also have website maintenance tasks that need to be completed regularly. The most obvious (and most time-consuming) of these is writing weekly blog posts. Beyond that, I also have some quality of life/user experience improvements that I occasionally work on. While such improvements can be time-consuming, they are fairly rare and have long-lasting impact, so they are often worth the time. I am currently in the middle of one such change, and planning a second change as well, so I thought that exploring this topic in a blog post would be both interesting and timely.
As a part of writing last week's post I decided to (finally) implement syntax highlighting for the code snippets on my blog. Syntax highlighting, for those that are unfamiliar, is the use of consistent visual changes (such as color or font) to distinguish between different elements of code. It is typically used to make code samples more readable, since readers can more readily focus on the content of the code, rather than having to worry about the structure of the code. As a simple example, here is the same sample code, both with and without syntax highlighting:
public void Example(string message){
Console.WriteLine("{0} world", message);
}public void Example(string message){
Console.WriteLine("{0} world", message);
}While small snippets of code usually don't benefit much from syntax highlighting, it can be a massive boon for larger code samples, especially if they are messy or complex.
While syntax highlighting is a technically complex task that varies based on the nuanced differences of each programming language, there are plenty of libraries available that will take care of the technical details. Of the available libraries, I (largely arbitrarily) decided to use prism js and I am reasonably happy with that choice. In particular, I am using a server-side implementation, so even readers that have javascript disabled can still benefit. One downside of the server-side implementation, however, is that it requires additional work to migrate any existing code samples, so (as of right now) most of the older blog posts do not yet use syntax highlighting.
One aspect of my written "voice" is that I make heavy use of asides. Simple asides often appear as inline parenthetical comments (like this,) however, for larger or more complex asides, using parentheses can interfere with the readability. Over time, I've experimented with a few different approaches to this, but I am still not happy with my current approach*. As such, I am looking at other options on how to convey this information.
One particularly problematic constraint on my use of asides is that it is tightly coupled to a particular point in the main work. In general, articles that effectively use asides tend to anchor them to the space between paragraphs rather than to a particular point in the text. While this makes sense structurally (paragraph breaks are the space between ideas) it has the effect of uprooting the aside, leaving it without the context from which the idea sprang forth. Some asides are isolated enough that this would be fine, but for asides that are contextually sensitive, authors often have to backtrack to rebuild that necessary context. Regardless of how much, or little, backtracking is done, such asides generally have a different feel to them: less like a stray thought captured for the reader's benefit and more like a stranger interjecting a thought of their own*.
While I do intend to continue looking for a better approach to communicate asides, in the short term I am planning a few minor improvements to the style. In particular, I would like to increase the text size to match the size of the rest of the article: this should alleviate issues where readers set their zoom level to comfortably read the main article, only to find the asides are uncomfortably small. I expect I will make this change unceremoniously in the coming weeks - perhaps as a part of my ongoing effort to update the old blog posts to use syntax highlighting.
Syntax highlighting has been a long time coming, and I am glad to have finally made time to work on implementing it. Yet there is still more to do, not least since asides, despite several revisions, are still a sub-optimal experience. Hopefully reading my thoughts about some of my site's user experience issues has been helpful for you (or at least interesting.) If you have any thoughts or feedback about any of this, please let me know.