Learning to write better

Hello! I’ve been so incredibly busy with university work these past three weeks (and this weekend is no exception), but I’ve been able to peel myself away for long enough to finally write a debrief.

I’ve done little on my projects but dream, so here’s a little of what I’ve been dreaming about.

Bedrock

I have a clear image in my head of what Bedrock will look like when completed: a series of documentation books, full support across a variety of platforms, a robust suite of useful software built on Bedrock, and a physical Bedrock machine built cheaply from a box of scraps.

The focus right now is on writing the documentation, everything else will flow from there.

What does good writing look like?

I’ve spent a bit of time working on the experimental one page spec, and I’ve come away with a sense of how much better the main specification could be if only I were to write it better. The current specification is precise and difficult to misinterpret, but it’s also verbose, long, and clumsy in structure. There was a blog post I read some years ago that talked about how improving the speed of an internal code review tool completely changed how people used it and worked with it, and I can see how that same idea applies here.

When a specification is short and concise, it’s just so much more enjoyable to read and understand, which means that it’s easy to write and verify an implementation against, which means that implementations will be easier to create and maintain. This will be a big force amplifier for me, it’s so incredibly important. This third revision of the specification should have the brevity and structure of the one page spec, but the clarity and careful wording of the current spec. Two parts one page, one part current spec. It truly is a delight to scroll through the one-page spec and see each device fit comfortably into one screen of space, it’s so easy to read.

How do I get there?

The structure is going to be a really big part of revision 3. I tried too hard to keep to the same structure for each device in the current specification, even though some of the devices are massive and some are trivial, and I also tried to avoid repetition by linking to shared concepts under a ‘types’ heading for each device. All that this accomplished though was to make the person reading have to jump around lots as they read, making everything harder to find and understand.

The other point to think on is clarity. Clarity is obviously the most important part of a specification, it has to be specific. It’s impossible to be completely clear though, I’m always going to be leaning on the reader already understanding some concept or another, and there’s a point of diminishing returns where you find that you’re no longer trusting your reader to act in good faith, where your writing starts to read more like legislation. I think a lot of the sentences in the specification could be made more concise without noticeably losing clarity, but I’ll need to play around with them to be sure.

I’ve been looking at the IEEE SA Standards Style Manual too, it looks like it’ll be useful for some of the tiny stuff that I’ve been unsure about (like usage of ‘that’ vs ‘which’ in the text, that sort of thing). It’s also just really nice to have a guide to follow, I’ve had a hard time finding any decent resources on writing a specification. My main approach so far has been to read decent looking specifications and then try to fit their structure to whatever I’m trying to accomplish. I might not use the IEEE manual much in the end, it depends how relevant it looks once I’ve read it properly, but I’m pleased with the find.

NightSky

I reconnected with a close primary school friend this past week and we talked for hours about game design for tabletop role-playing games. It really helped me to clean up my ideas and figure out what I’m trying to accomplish with NightSky, the minimal tabletop role-playing game system that’s been loitering on my projects page for a while now. IThe best way to describe it is that it’s a sandbox rules framework for sandbox games.

What does that mean?

NightSky will be a framework that offers a tiny, flexible core and encourages scrappy rules and subsystems to be bolted onto the sides to add nuance and complexity. I don’t want a system like Dungeons and Dragons where every rule is sacrosanct and players pore over footnotes like lawyers in court. I’d rather the game looked more like a folder of badly photocopied pages torn from forgotten game books, held together with creativity and spit, where the rules can change to match the shape of the world being explored. I read an idea a while back about how user interfaces in video games rarely ever change as you play the game; this would be like a game where the interface changes as the game progresses, the rules being just another part of the game to play with.

I also want a game that’s quick and lightweight at its core: a game that can be played in a busy library, or while waiting for a bus, or out in a grassy paddock on a lazy afternoon, under the gentle shade of an old tree. A game that can be started in the time it takes to open your bag, without the ceremony of character sheets and backstories, and packed away on a dime for later.

I first discovered Dungeons and Dragons back in high school, trying to figure out how to play the thing by reading through the absolute encyclopedia of a player’s handbook (3.5e) start to finish. I didn’t yet know anything about the complicated lineage that led to this bloated chimera of a system landing in my lap, but it seemed like there was the spark of a better, smaller system hidden deep inside (if only one could find it beneath the teetering pile of rules for guisarmes and keelboats and cephalopod companions). NightSky is my attempt to realise this feeling.

Maybe I’ll write more on my explorations in the future. There’s still so much to be explored here.

University

I’m not sure there’s much to say here. I’m taking a maths paper, a physics paper, a general science paper, and a fine art photography elective this semester — it’s really busy but I’m having fun with it. The goal is to be eligible at the end of the semester to transfer into the engineering programme, but it’s gonna be a tight one, there’s only 30 slots and there’s probably around 200 hopeful applicants.

Thanks

Mid-semester break is coming up, I’m looking forward to finally having some time to sink into this stuff. Thanks for the interest and support in the meantime. Until next time!