Really enjoyed the conversation between Sam Harris and George Saunders. I’ve not read anything from Saunders, but they had quite an insightful discussion about writing and culture (and a hint of politics) that it might be worth looking at some of his fiction. 🎙️
Almost didn’t make it to the gym this evening. Glad I had a change of heart. Also glad that it came while the gym was still open.
(I say “change of heart”, as if the decision was made in the abstract. But it was the bad, guilty vibes that actually drove me to go.)
Gave the sample Storytime episode for my train line a try, and it’s not for me. Aside from being something not available wherever I get my other podcasts, the sample was really overproduced, with backing audio and cheesey sound effects. Not a fan of those sorts of podcasts.
The nature of AWS is that, even with things like ChatGTP, there are still traps laying about for those poor souls that don’t know what they don’t know. For example: did you know that you cannot immediately delete a secret value? You can only “schedule” it to be deleted at a future date that’s no earlier than 7 days from now. The secret won’t show up in the console, but you can’t use the same secret ID until it’s actually gone.
So good luck recovering from any mistakes you’ve made creating a secret via the AWS console instead of using Cloud Formation, like I did today. I guess some things’ll never change.
Been working on a Cloud Formation stack that defines IAM resources: roles, policies, profiles, etc. I can do a little bit already, like change policy documents, but writing this all from scratch is beyond me. ChatGPT has been a great help here. Would’ve been bothering my coworkers all day otherwise.
Code merged and artefacts prepared. Now to deploy it on brand spanking new infrastructure.
Damn devs deploying on my shiny new infra 😔 pic.twitter.com/B64JCvm4eI
— Simpsons Against DevOps (@SimpsonsOps) August 8, 2021
So, this is how my morning went.
Apologies to my reviewers for all the notification emails they’re receiving during this battle with the CI/CD build.
Might be the only way I’ll learn another language is I put the spoken training audio to music, preferably something that can pass as a entry to Eurovision.
Linux administration is quite fun. I don’t usually get an opportunity to do it as part of my day-to-day, so it’s always a joy having a task that involves SSH and interacting with a shell. 🐧
📺 Fallout: Season 1 (2024)
👨💻 New post on Linux over at Coding Bits: Packaging Services With Systemd
📝 New post on Blogging Tool over at Workpad: More Tools For Blogging Tool
Oof! These mornings have been really cold this last week. Had to bring out my wool and possum fur gloves for the walk to the cafe in 0.5°C weather.
🔗 Adding Github-Style Markdown Alerts to Eleventy
GitHub has alerts (aka callouts) Markdown support where the syntax looks like [Obsidian’s.]
So apparently, if we were using Github instead of Gitlab, I could’ve had it all. 😏
One other thing I found this morning during my exploration of Markdown and Asciidoc is that many tools have a problem with JSON code blocks containing JavaScript-like comments. They’re reported as syntax errors, and sometimes they break the syntax highlighting. They’re still included in the rendered HTML, but it feels to me like the tools do so begrudgingly. Gitlab even marks them up with a red background colour.
Why so strict? The code blocks are for human consumption, and it’s really useful to annotate them occasionally. I always find myself adding remarks like “this is the new line”; or removing large, irrelevant chunk of JSON and replacing it with an ellipsis indicating that I’ve done so.
I know that some Markdown parsers support line annotations, but each one has a different syntax, and they don’t work for every annotation I want to make. But you know what does? Comments! I know how to write them, they’re easy to add, and they’re the same everywhere. Just let me use them in blocks of JSON code, please.
Oh, and also let me add trailing commas too.
Asciidoc, Markdown, And Having It All
Took a brief look at Asciidoc this morning.
This is for that Markdown document I’ve been writing in Obsidian. I’ve been sharing it with others using PDF exports, but it’s importance has grown to a point where I need to start properly maintaining a change log. And also… sharing via PDF exports? What is this? Microsoft Word in the 2000s?
So I’m hoping to move it to a Gitlab repo. Gitlab does support Markdown with integrated Mermaid diagrams, but not Obsidian’s extension for callouts. I’d like to be able to keep these callouts as I used them in quite a few places.
While browsing through Gitlabs’s help guide on Markdown extensions, I came across their support for Asciidoc. I’ve haven’t tried Asciidoc before, and after taking a brief look at it, it seemed like a format better suited for the type of document I’m working on. It has things like auto-generated table of contents, builtin support for callouts, proper title and heading separations; just features that work better than Markdown for long, technical documents. The language syntax also supports a number of text-based diagram formats, including Mermaid.
However, as soon as I started porting the document over to Asciidoc, I found it to be no Markdown in terms of mind share. Tool support is quite limited, in fact it’s pretty bad. There’s nothing like iA Writer for Asciidoc, with the split-screen source text and live preview that updates when you make changes. There’s loads of these tools for Markdown, so many that I can’t keep track of them (the name of the iA Writer alternative always eludes me).
Code editors should work, but they’re not perfect either. GoLand supports Asciidoc, but not with embedded Mermaid diagrams. At least not out of the box: I had to get a separate JAR which took around 10 minutes to download. Even now I’m fighting with the IDE, trying to get it to find the Mermaid CLI tool so it can render the diagrams. I encountered none of these headaches when using Markdown: GoLand supports embedded Mermaid diagrams just fine. I guess I could try VS Code, but to download it just for this one document? Hmm.
In theory the de-facto CLI tool should work, but in order to get Mermaid diagrams working there I need to download a Ruby gem and bundle it with the CLI tool (this is in addition to the same Mermaid command-line tool GoLand needs). Why this isn’t bundled by default in the Homebrew distribution is beyond me.
So for now I’m abandoning my wish for callouts and just sticking with Markdown. This is probably the best option, even if you set tooling aside. After all, everyone knows Markdown, a characteristic of the format that I shouldn’t simply ignore. Especially for these technical documents, where others are expected to contribute changes as well.
It’s a bit of a shame though. I still think Asciidoc could be better for this form of writing. If only those that make writing tools would agree.
Addendum: after drafting this post, I found that Gitlab actually supports auto-generated table of contents in Markdown too. So while I may not have it all with Markdown — such as callouts — I can still have a lot.
Must say I enjoyed The Rest Is History’s recent podcast on Dragons. They go into how these mythical beasts developed over the years, how they’re seen differently in different cultures, and how they entered the mainstream. Just watch out for the odd spoiler for House of the Dragon series 1. 🎙️
Eight months in and I’m still enjoying writing technical documents in Obsidian. I’ve never really appreciated how well it works for this form of writing. I wish we were using this for our knowledge base, instead of Confluence.
Key ring.
It’s always after you commit to a deadline that you find the tasks that you forgot to do.