Writing Clear Instructions

Back in May, I started running a new writing class called Placing Your Mark.

Unlike the other events I run, where the members bring their existing projects, this one is actively geared towards creating new work. The format has now settled down to include regular features such as writing a passage containing five given words, starting with a line taken from a novel, or inspired by picking a card at random.

When I’m writing these prompts, I do it by myself and it’s difficult to tell how well they’ll be understood.

For example, there is always a break halfway through, during which I produce an object and ask the members to muse upon it and write a piece inspired by it. I initially thought I was making the intention clear: a ten-minute break, followed by five minutes of writing. After trialling the feature and finding members were confused, I rewrote the instructions to make it clearer.

Other prompts don’t fly as well as I’d hoped. A few of these have involved an office setting, which frequently has a power structure and is ripe for conflict. However, some members have had difficulty relating to this because they haven’t worked in that type of environment.

Based on this feedback, I’ve had less of a problem with prompts that don’t work. It’s just as well because we’re now into the third block of four sessions, with possibly enough interest for a future block, and that means I need to write even more of them.

CSI for CSS

Until September of last year, my open-mic event would circulate bulletins using a manually-maintained Gmail list. This is not designed to send 50-plus messages at once and the system eventually refused to send certain ones. So it was time to set up a more modern self-service system, and here’s the entry about what happened at the time.

For GDPR compliance, we also needed to set up a basic website to allow members to join and leave. Our Web server would then deal with the request automatically. I found an open-source template online and stripped it down to suit our needs. Everything else on the website was initially a secondary concern, but we’ve slowly expanded the content to include event times, standards of behaviour and the latest bulletin.

While running a link check, I spotted six broken ones. They weren’t important, merely referring to fonts that weren’t in use on the site, but I wanted to understand the errors and fix them.

It transpired that our site was referencing two separate Cascading Style Sheet (CSS) documents. These are used to define the visual appearance and layout of a Web page, including the colours, fonts, spacing and positioning of elements. Worse, the two documents contained some contradictory information, so the functionality of the website could change or break depending on the order in which the instructions were executed.

Combined with a little sloppy HTML syntax, the browser was doing some heavy lifting to correct the errors silently behind the scenes. Remembering the experience of the distribution list, I didn’t want this to collapse as well.

I used to be a lot more interested in computing than I am now, so much of my coding knowledge has left me. But I spent the weekend combining the two sheets and figuring out what could and should be removed. I relied heavily on user questions from Stack Overflow, the output from code validation websites and even ChatGPT to write snippets of code or check what I’d written.

Ultimately, a total of 7,800 lines of CSS code were reduced to less than 160 lines by Sunday night. The resulting Hotchpotch website is still incredibly static and basic, but it fits the bill precisely.

I then had the impetus to revamp an existing website for a small writing class I’ve been running. This time, I used authoring software for the general look and feel, then made small revisions to the code by hand with my newfound knowledge. The Placing Your Mark website is much more dynamic than its Hotchpotch cousin, although I might one day harmonise their respective designs.

Meanwhile, with the bank holiday weekend over, I’m excited to get back to writing words and sentences rather than syntax and semicolons.