I pushed out my Joys of a Simple Site post to Mastodon, Twitter, and all Webmention enabled end-points. The post garnered a few responses. In particular, I wanted to follow-up on a thread between Alex Schroeder and I. Note: Alex gave me permission to post his response.
Here’s Alex’s response:
@takeonrules hehe, for certain definitions of “simple” of course. All those scripts and tools you do use don’t seem to be simple to use. It’s about access to the raw storage (files), management tasks (tools), transferred objects (how many files, which files). Too add more simplicity one would have to go to static files without a generator, I think. Or maybe just one “generate HTML” step.
And my response to Alex:
@kensanata absolutely!
In my case, simple for me are scripts that have narrow/single responsibilities. Which keeps maintenance simple. These scripts rely on libraries, which adds complexity.
In other words…
Someone Pays for the Simplicity
I spend a lot of time thinking and writing about both software and Role Playing Games (RPGs 📖). I consider the cognitive load of these activities, and how I might reduce that load. Oddly this is only the second time I’ve written “cognitive load” in my blog. The first time was two years ago, as a sidenote.
I want to look at two examples.
First a Game Example
Let’s talk about Dungeons and Dragons (D&D 📖)—After all this is a blog about games, though I’ve certainly expanded the scope to include software and general hobbies.
In Dungeons and Dragons: Fifth Edition (5E 📖) the adventure designers at Wizards of the Coast (WotC 📖) have committed to referencing monsters with bold and italic letters. For example, you might encounter the following sentence:
Six ogres guard the room.
As a reader, that sentence carries little cognitive load. However, in WotC published adventures, that sentence will be part of lengthy paragraphs. When authors are paid by the word, expect wordiness.
One barrier of cognitive load is how difficult it is to scan the text. The adventures are structured to read like fiction. When running the adventure at the table, I want the document to better communicate the salient information.
Another barrier is that I need to know where to go to find the keyword ogres. This involves either flipping to another section in the book or opening a separate book. If I used a tool like Roll20, I might have access to hyperlinks. But I prefer my game books in dead tree form. I can mark them up in the margins.
A third barrier emerges when you flip to the 5E Ogre stat block, you need to parse that information. And woe is you if you have to reference multiple creatures.
One advantage of naming something, but not including inline stats, is the implication of portability. After all, I could reference the Sword & Wizardry Ogre. Or the Dungeons and Dragons: Third Edition (3E 📖) Ogre.
Let’s quickly look at inlining a Dungeon Crawl Classics Ogre:
Six ogres (Init +2; Atk slam +5 melee (1d6+6) or great mace +5 melee (1d8+6); AC 16; HD 4d8+4; MV 20’; Act 1d20; SpP bear hug; ST Fort +4, Ref +2, Will +1; Al C) guard the room.
As someone familiar with Dungeon Crawl Classics (DCC 📖), I have enough information for play. While running the adventure, if I see this line, I don’t need to flip to another section or open another book.
However, someone new to DCC might baulk at this, raising their cognitive load.
Second a Code Example
Second, let’s look at the aforementioned ABBR tags.
Sprinkled in this post are several uses of the ABBR tag. The letters with a dotted underline are abbreviations. Mouse over those abbreviations and you can see my definition of that abbreviation.
This site uses a lot of jargon and abbreviations. Most everyone that I know has encountered the abbreviation “PC”. And in the context of my site, “PC” could mean Player Character or Personal Computer. And some might expand “PC” to mean Political Correctness.
, I spent time working through the abbreviations on my site. In part a software scripting exercise, but also to help improve accessibility for my readers. Accessibility is more than “Does my site work on a screen reader”. Accessibility is a commitment to help people access and engage with your content.
Under the hood I have encoded complexity; All to help deliver a more accessible and hopefully simplified experience to you the reader.
My Hugo (Hugo 📖) shortcodes/abbr.html…
{{- $key := .Get 0 }}
{{- if isset .Site.Data.abbrs $key }}
{{/* We have the given key in our abbreviations repositoy *//}}
{{- $data := index .Site.Data.abbrs $key }}
{{- $title := index $data "title" }}
<abbr
{{ with $data.itemid }}
itemscope itemtype="http://schema.org/Thing"
itemid="{{ . }}"
{{ end}}
title="{{ $title }}"
>
{{ if isset $data "abbr"}}
{{$data.abbr}}
{{ else }}
{{ $key }}
{{ end }}
</abbr>
{{- else }}
{{- $singularized := replaceRE "s$" "" $key }}
{{- if isset .Site.Data.abbrs $singularized }}
{{/* We have a singularized version of the given key *//}}
{{- $data := index .Site.Data.abbrs $singularized }}
{{- $title := index $data "title" }}
<abbr
{{ with $data.itemid }}
itemscope itemtype="http://schema.org/Thing"
itemid="{{ . }}"
{{ end}}
title="{{ $title }}"
>
{{ if isset $data "abbr"}}
{{ $data.abbr }}
{{ else }}
{{ $key }}
{{ end }}
</abbr>
{{- else }}
{{/* No hit for now. We'll handle this later *//}}
<abbr>{{ $key }}</abbr>
{{- end }}
{{- end }}
What’s going on in the above code?
First, to invoke the code, I write {{< abbr “PC” >}} in the body of my post.
On my site, I believe “PC” always refers to Player Characters.
I also wrote an atom package where I can select a word and type Cmd + Ctrl + a. That command will then convert the selected word to the Hugo shortcode for an abbreviation. That shortcut sure was handy when I added abbreviations to the above DCC inline stat block.
The “PC” is the $key for the short code (line 1 of the “shortcodes/abbr.html” code).
If that $key exists in the glossary of terms (e.g. .Side.data.abbrs ), I use that abbreviation’s glossary entry. If there is no match for the $key, I try the $key without it’s trailing s.
Assuming I find a match for the $key, I then if that abbreviation has an itemid, I add an itemscope, itemtype, and itemid attribute to the ABBR tag.
Often times, that itemid points to a Wikidata.org entry. From there, you the reader, can delver further into the specific term I referenced.
If the $key does not match, I indicate that this is an abbreviation, but one for which I don’t have a title.
Later in my publishing build scripts, I audit the site to ensure that every ABBR tag has a title. I also repurpose these abbreviations to add “about” property to the site’s Javascript Object Notation for Linking Data (JSON+LD 📖). But that’s another complexity for another time.
Conclusion
In every simplification someone or something pays the cost to make it simple. And what is simple for one person may be difficult for another.
Keeping things simple involves focusing on single responsibility. For example, I have a “simple” script to push my posts to Mastodon. And one script to push to Twitter. And a third script that pushes out my Webmentions. I also have a script that runs those three scripts.
And lastly understand, when you step away from something, it’s likely you’ll come back to it much later. You’ll thank yourself for this simplicity.