Tools I use when writing documentation

I’ve just finished what felt like the worlds longest work instruction, and it made me think… I’ve got these great tools at my disposal for when I’m writing documentation – perhaps not everyone knows about them!?

So here are the main ones!

Open Broadcaster Software (OBS) Studio

OBS Studio is a screen recording application, most commonly used by eSports players and gamers to stream content to streaming platforms like Twitch. While it’s really easy to do stuff like “lower third” bars (like this)

It’s also really *really* easy to just record a screen, which makes it easy to just “set and forget” and then run through the tasks. In the past, I’ve been on highly-technical in-person training courses and run OBS while I’ve been in a room, just to make sure I didn’t miss any details when I went back over my notes later!

Clicking “Start Recording” in the bottom third of that screen starts writing the content of that screen into (by default) a MKV file in your home directory (on Linux), or into your Videos directory on Windows. I don’t recall where it went on OS X!

This means after the task is done, I can play it back with…

VideoLan Client (VLC)

VLC is (or, at least, was) the defacto video player for anyone who consumes media on their computer. In my case, I only really use it now for playing back files I’ve recorded with OBS, but it’s a great player.

I only really make one key change to VLC, which is; adding the playback speed buttons. Different platforms do it differently, but on Linux and Windows at least, go to Tools -> Customise Interface and you’re presented with a screen like this:

I drag the “Slower” and “Faster” buttons to either side of the stop button, and will typically play videos back at 3x or even 8x speed to get to the areas I want, and then slow it down, sometimes, to 0.5x speed to get specific frames I’m looking for.

Once I get that frame, I’ll use a…

Screen Snipping Tool

On Windows this is the built-in snipping tool, found by pressing Windows+Shift+S. On Ubuntu, I’ve installed the package gnome-screenshot and the Gnome Extension Screenshot Tool.

With Snipping Tool you can draw circles around things and make annotations with a pen, but in extreme cases, I rely on the …

GNU Image Manipulation Program (GIMP).

GIMP, aside from being a badly named project (notably because most people over a certain age know about that scene from Pulp Fiction) is a FANTASTIC image editor. I use it for all sorts of editing, cropping and resizing, but I particularly love the layers menu on the side.

A couple of years ago my son wanted to give all his friends “membership cards” for a club he’d made. These were created in GIMP and just required him to clone a layer from the block on the right, hide the previous layer, and change the text in the clone.

This also means that if you want to easily highlight specific areas of the screen it’s only a few clicks to do it. Now, that said, it’s not as straightforward as Paint, and for anything beyond easy tweaks it will take a bit of experience, but it works.

This is all well and good, but sometimes you just need details from a terminal, where I’d use…

Asciinema

I use Asciinema (just a pip, apt or rpm away) when I’m working on something on a command line that I want to play back as a video, and the main reason is that I can adjust my output really quickly and easily!

Consider this screen of data:

I “recorded” that using asciinema rec ./demo.rec and ended it with ctrl+d. That created a file called demo.rec, which looks like this:

Each line is prefixed with a timestamp, it then has a stream action (mostly o for “output”, but you can add m for “marker” or i for “input” in there if you wanted to be clever ;) ) and then the text which will be rendered when it’s played back (more about that in a tic). This means that if you make a drastic typo, you can fix it in this file, or if you want to redact a password that you never meant to type, you can do!

But, and here’s the next awesome thing, you can also ask it to play back ignoring any gaps longer than X amount of fractions of a second, so if you went off to make a coffee in the middle of doing a recording, playback won’t show it.

And then, playing it back… well, you can just run asciinema play demo.rec but that’s a bit boring… but you can link to it, like this demo I created a while ago or even embed it in your own site

Rendering it all

And the last thing I use? Whatever writing tool I have to hand! I typically write on my blog if it’s for public consumption (like this), but I’ve used private Github and gitlab repos, Visual Studio Code to create markdown files, Google Docs, Microsoft Word, LibreOffice Writer and even slide decks if it’s the right tool for the job.

But the most important thing is that you get your documentation OUT THERE! It’s so frustrating only having half a story… like this one:

This is an XKCD Comic titled "Wisdom of the Ancients" which has the alt-text:
"All long help threads should have a sticky globally-editable post at the top saying 'DEAR PEOPLE FROM THE FUTURE: Here's what we've figured out so far ...'"

It depicts a stick figure shaking his screen, and a series of lines of text which say:
"Never have I felt so close to another soul and yet so helplessly alone as when I Google an erorr and there's one result a thread by someone with the same problem and no answer last posted to in 2003"

Above the stick figure is the text "Who were you DenverCoder9? What did you see?!"

Featured image is “Tools” by “Paul Downey” on Flickr and is released under a CC-BY license.

"Apoptosis Network (alternate)" by "Simon Cockell" on Flickr

My Home Automation Tooling and Devices

Following a quick conversation with a neighbour today, I thought I’d do a run-down of (and links to) the technology I’m using in my house :)

The devices

Amazon Alexa and Fire Devices

I’ve been a fan of these for some time! I have Echo Dots, an Echo Show and a few Echo Flex devices. I also have an Echo Auto, which was rubbish.

My TV, although it’s nominally “smart”, I prefer to be able to swap out the “smart” part, and so I also have a Fire TV stick for actually consuming content. I previously tested a FireTV Cube, and would have loved to have kept that, but I had to return it.

Ring Stick-up Camera

In a previous role, I was asked to test a Ring Stick-up Camera. When I left, they said I was allowed to keep it. The device is OK, but I probably wouldn’t have bought it if it wasn’t sent to me.

Tuya Wifi Enabled Light and Mains Switches

I have a few different models of these things. Most of them are used just as wi-fi power switches, but a handful of them also do power monitoring too. In my last set of works, I also got a couple of the light switches too.

Computers

Previously, I was using a handful of Raspberry Pi devices to run all of this lot. I had a Raspberry Pi 4 Model B, 4GB and a couple of the Raspberry Pi 3 Model B+ devices too. Recently, I’ve moved all my main computing workloads off these, and on to a pair of these Dell Optiplex 3040M i5 with 16GB RAM. That’s not to say they’ve gone unused now (no, I’m running Octopi amongst other things) but my main lab stuff isn’t on those any more.

The software

Hypervisor: Proxmox

Previously (pre-Pi), my computers would be running an Ubuntu variant, and everything would be running Docker containers or virtual machines with Vagrant, but after the last few months of wall-to-wall Proxmox recommendations, when I got those two PCs, they were immediately setup as a Proxmox Cluster. I did a few of the tweaks from tteck’s Proxmox VE Helper Scripts page.

Storage: gluster

I have a cluster of two machines, and I want to be able to migrate between the pair of them. To get this working, I setup Gluster following this YouTube tutorial. This gives me storage across the pair of servers, and lets me live migrate any virtual machines and containers between the pair of them. At some point in the future, I’ll be setting up nfs-ganesha-gluster on there too, to allow virtual machines to have object storage rather than block storage as needed.

Home Automation: Home Assistant OS

This was what I was running on my Raspberry Pi, and so it was a no-brainer to port the configuration over. While I could have set a virtual machine up by hand, instead I used tteck’s helper script, which asked me to run this command:

bash -c "$(wget -qLO - https://github.com/tteck/Proxmox/raw/main/vm/haos-vm.sh)"

It’s always slightly suspicious when someone asks you to run a shell script without checking it, so I downloaded the script first, checked it over (as much as one can), and then ran it from the system. It’s not the most secure way to do it, but I was satisfied with what I was seeing that let me trust it.

Remote access: Tailscale

Tailscale is a mesh VPN product, using the great Wireguard VPN product. I previously experimented with Nebula, and while I’d still endorse it to anyone who is keen to run their own infrastructure, sadly I failed on certificate basics with Nebula on my home network, and Tailscale moves all that away from my headspace. I can see more scope for automation with Nebula, but the extra controls needed were too much for me.

Plugins, Extensions and Add-Ons

Android App: Home Assistant

OK, so this is more of a “nice to have” than a “needed” thing, but with this I can determine who’s in the house, and can track battery usage for the devices. It also means I can see and manipulate the Home Assistant dashboard.

Android App: Smart Home (Tuya)

Only really needed for the initial set-up of the Smart Devices, sometimes it’s useful to see power used over time, or to find out what the MAC address of the device is (for making sure it’s on your network), and whether it’s actually getting a reasonable signal from your WiFi router.

Home Assistant Add-ons: HACS and Alexa Media Player

HACS is a meta-add-on; it helps you to add more integrations to Home Assistant. With this, I can integrate my Amazon Echo devices.

Home Assistant Integration: Tuya

This is how I control my smart switches and monitor the power consumption. I needed an account on the Tuya IoT platform and the SmartHome Application.

Configuration

Home Assistant Blueprint: “Turn a switch off after a defined set of time”

I followed this thread (which didn’t give me what I needed), and ended up writing my own blueprint. I use this for things like radiators and heated blankets.

Home Assistant Blueprint: “Notify or do something when an appliance like a dishwasher or washing machine finishes”

I … um … use this exactly as defined; it’s hooked up to the switch on the washing machine and dishwasher, and notifies me via Pushbullet when they’re both done, giving me a fighting chance of emptying them before my wife has to.

Featured image is “Apoptosis Network (alternate)” by “Simon Cockell” on Flickr and is released under a CC-BY license.

Releasing a Presentation on “An introduction to Multi-Factor Authentication (MFA)”

Over the last year, the team I was in had a routine that every week we’d have a briefing-come-good-news meeting. About a third of the way through the year the routine changed and it would be fronted by a presentation on a subject of interest to that team member. It was loosely encouraged to be relevant to the job, but it wasn’t a formal requirement.

For whatever reason, my slot got bumped (I think it was the day of the Queen’s funeral, but I’m not sure), and then I rescheduled myself for December… and the meeting was cancelled as we were having an in-person meetup. Bah.

Anyway, I wrote a deck, and planned to deliver it. That isn’t going to happen now, so I’m releasing it for anyone to read, or maybe even play Powerpoint Karaoke with.

Click here to visit the deck. Press “S” to see the speaker notes (you’ll need them!)
LEGO Optimus Prime set 10302 in vehicle mode, with the axe, jetpack and Energon cube on the table alongside the informational plaque.

My review of the LEGO Optimus Prime set 10302

My history

Earlier this year LEGO released the Optimus Prime set, 10302, and I said to my friends at the time “£150… It’s good, but is it that good? (Who am I kidding… Add to basket)” but, of course, I didn’t.

Later in the year, I was fortunate enough to visit Billund in Denmark, the home of LEGO, and I got to see the glory of the Optimus Prime set in the … plastic? Anyway, because I was there with hand luggage only, I couldn’t fit the box and set into the luggage, so I couldn’t get it abroad, and assumed that was it – no more Optimus for me.

Until Christmas Day arrives, and my (amazing, beautiful, best person ever) wife hands me a box… As I pick it up from her, I say “That… sounds like Lego” but I still haven’t put two-and-two together yet. I peel open the paper and my mouth drops. It’s this set.

See, I’m of the era that watched all the cartoons, had all the comics, and (thanks to, in hindsight, my verygenerous parents) had a few of the toys… so this is a true throwback for me.

The build itself

Jules and I agreed that today would be the “build our Lego sets” day, so as I started my breakfast I cracked open the box.

The Optimus Prime LEGO set (10302) box, showing the robot-form.
The Optimus Prime LEGO set (10302) box, showing the robot-form.
The rear of the box shows the transforming model, plus the accessories which come with the build.
The rear of the box shows the transforming model, plus the accessories which come with the build.
11 bags of the LEGO Optimus Prime set 10302, plus a cardboard envelope containing instructions and 5 stickers.
11 bags of the LEGO Optimus Prime set 10302, plus a cardboard envelope containing instructions and 5 stickers.

I set to work. Right from the outset, the classic windscreen was visible, and it’s a perfect opening section for the set, and builds the anticipation for the final build.

The result of the first bag of lego - the classic windscreen for Optimus which hides the Matrix of Leadership (built later)
The result of the first bag of lego – the classic windscreen for Optimus which hides the Matrix of Leadership (built later)

Several hours later (including a few rounds of Singstar and Buzz, lunch and dinner), Optimus Prime is complete.

The completed model, standing in robot form, with gun in hand. Axe and Energon cube on the table in front of the robot, and a plaque about Optimus Prime.
The completed model, standing in robot form, with gun in hand. Axe and Energon cube on the table in front of the robot, and a plaque about Optimus Prime.
LEGO Optimus Prime set 10302 with the axe in hand and the Energon Cube, gun and plaque on the table in front of Robot-Form Optimus Prime.
This time Optimus in Robot-Form, with the axe in hand.
LEGO Optimus Prime set 10302 features a detachable jetpack as part of the build.
And finally, in robot form, showing off the detachable jetpack.
LEGO Optimus Prime set 10302 in vehicle mode, with the axe, jetpack and Energon cube on the table alongside the informational plaque.
In vehicle mode, the gun is part of the wheel-train, but the axe, Energon cube and jetpack need to travel separately!

Conclusion

This was a great build, and I’m glad I got the set – I’ll have plenty of enjoyment from showing it off and transforming it. I’m also really impressed at the level of detail they’ve gone into (although, to be fair, the grand piano which I got for Jules last year also set this bar pretty high).

Total build time was probably about 6 hours all-in, mostly building by myself, although Emily weighed in and helped for a bit. There were just enough pieces in each bag to justify having a new bag, but probably could have reduced things down to about 6 bags without too many worries.

It’s mildly frustrating that the jetpack and axe aren’t somehow incorporated into the vehicle-form, and the axe does occasionally fall off or pull the arm off, but, eh… it’s just there for the battles, and he’d be more likely to just shoot the gun. These are definitely things I can live with, I just need to be sure I don’t lose them!

So, final review – glad I got it, and the build revealed a few Easter eggs about the build that I really appreciated. 9/10

Thinking of getting the set? Consider buying it through my referral link: Amazon UK

Barcamp Manchester 2022 – my review

Outside of work, I attended my first technical event since the 2020 lockdown. A Barcamp is a community run conference where the attendees propose the talks they want to present. In past years, I have attended with an intention to speak, and in some cases present several talks.

This a a picture of “the grid” – the cards on the far left are the rooms in which talks occur, the cards on the top row are time slots in which talks were to be delivered, and the rest of the cards were proposed talks.
This picture by Martin Rue on Twitter and used with his kind permission.

The first talk I attended was a talk by Patrick Hurley who was asking people to propose ideas to that would benefit people in the north of England. These will be written up into a book and used as inspiration for projects big and small. Well worth a look! 100ideasnorth.org

I missed the next slot, as I was making my way around groups of people I’d not spoken to for a while, but then my next talk of interest was “I’m an AWS Engineer… Ask me Anything (we’re hiring)” by Martin. I didn’t know anyone else from AWS was going to be there, so I went, if only to introduce myself and say hi… Well, one thing lead to another, and then I found myself joining Martin answering questions from my perspective in a different part of the organisation. I loved this session, and I’m really glad to have caught up with Martin, if only because he was such a lovely man and so enthusiastic about everything he was talking about!

After that, I went to the talk about Living in Japan by Fran. This was a quick ad-hoc talk, but totally adorable because it was just completely heartfelt and had loads of questions that were answered with fab anecdotes about life at a ladies-only university outside Tokyo… the questions were really good too!

Over lunch and slot 5, I put together a talk about my boardgame collection, and agreed to co-host a talk about working at AWS with Martin again.

I also found myself in a small talk, hosted by Harper, the 8 year old daughter of one of the attendees, who was very keen to present her first talk. It was a beautiful and well delivered talk about the elements of a pen, her favourite pen and what each element is for. She also fielded questions from the audience with a lot of confidence and spoke with great authority. She was fab, and I made a point of letting everyone I saw know about her talk!

I went to a talk in Slot 6 called “Dude, where’s my meetup” – a slightly confused talk which seemed to be asking “what happened to all the groups that met up in Manchester”, while also not being clear whether it was asking “and who’s going to run them again now we’re all meeting back up” or “why haven’t they restarted” or “what is replacing them” or even “why aren’t the groups which have restarted making more noise about themselves to make them found”… I plugged the North West UK Tech Community and encouraged groups to register themselves on there, and individuals to help clean out older groups that have closed.

I gave my talk on the Board Game spreadsheet I have created, and got a great couple of ideas on categorising the games we have, and whether expansions should be games in their own right, or not. Several people took links away, and I picked up this great alternative version that I could be reusing!

Next up was the conversation with the audience about working at AWS. Lots of really good questions again, and Martin and I developed quite a good raport. I think we’ll be trying to do things like these talks again!

After that session, I spoke to one of the audience members from the AWS session about being recruited by AWS, and then to another person about how they were using AWS. I really enjoyed being part of a conversation about how other people see AWS – I know it’s a lot of my day job, but it was just a nice reassurance that it’s not just something I can do inside my working hours!

Then we had the wrap-up, and there were lots of claps and cheers for the organising team and for anyone who spoke at the event. Great work everyone!

Afterwards, I went to the pub with some people who used to go to Geekup (and it was glorious!) and then made my way home.

All in all, a great day, and I’m looking forward to the next one!

"matrix" by "Jordi nll" on Flickr

I’m on a #Podcast: “It’s a Chat Episode 53 – More! – #TheMatrix: Reloaded”

Yep, they let me back on! And so, following the last recording (probably around November-ish), we recorded the chat that became Episode 53 of the It’s a Chat podcast. Much like the last episode, we talk about things which are connected to The Matrix: Reloaded (and get about 1/3rd of the way through the film), and talk about other stuff as well. I talk a fair amount about the Animatrix and we briefly discuss the game (that I don’t think any of us played).

I reference a series of books which I read, that I referred to as “Sand” but instead actually meant the first book, called “Wool” of the series “Silo“, which I rated 3/5 on Goodreads.

I also draw a conclusion that Agent Smith is actually rickrolling us, four years before rickrolling was a thing.

Featured image is “Matrix” by “Jordi nll” on Flickr and is released under a CC-BY-SA license.

"matrix" by "Dako Huang" on Flickr

I’m on a #Podcast: “It’s a Chat Episode 52 – Red Pill, Blue Pill – #TheMatrix”

A few months ago, I recorded a podcast episode with the “It’s a Chat Podcast” team, talking about The Matrix. We’ve got some subsequent episodes recorded about the sequels, but they’ve not been released yet! The first episode was released today as “Red Pill, Blue Pill – The Matrix“.

“It’s a Chat” talk about films, tv series and even games that were large parts of our lives growing up, including Star Wars, Ghostbusters, Indiana Jones and Star Trek.

Listening back to the episode today, it’s clear that I’ve not got any better at stopping the “Um”ing – so… I guess I need to do something about that :)

I’d love to hear your views on my views about the show, so please comment below, reply to the tweet or just message me using one of the links under “Where to find me” on my blog!

Featured image is “Matrix” by “Dako Huang” on Flickr and is released under a CC-BY license.

"raspberry pie" by "stu_spivack" on Flickr

Post-Config of a RaspberryPi Zero W as an OTG-USB Gadget for off-device computing

History

A few months ago, I was working on a personal project that needed a separate, offline linux environment. I tried various different schemes to run what I was doing in the confines of my laptop and I couldn’t make what I was working on actually achieve my goals. So… I bought a Raspberry Pi Zero W and a “Solderless Zero Dongle“, with the intention of running Docker containers on it… unfortunately, while Docker runs on a Pi Zero, it’s really hard to find base images for the ARMv6/armhf platform that the Pi Zero W… so I put it back in the drawer, and left it there.

Roll forwards a month or so, and I was doing some experiments with Nebula, and only had an old Chromebook to test it on… except, I couldn’t install the Nebula client for Linux on there, and the Android client wouldn’t give me some features I wanted… so I broke out that old Pi Zero W again…

Now, while the tests with Nebula I was working towards will be documented later, I found that a lot of the documentation about using a Raspberry Pi Zero as a USB gadget were rough and unexplained. So, this post breaks down much of the content of what I found, what I tried, and what did and didn’t work.

Late Edit 2021-06-04: I spotted some typos around providing specific DHCP options for interfaces, based on work I’m doing elsewhere with this script. I’ve updated these values accordingly. I’ve also created a specific branch for this revision.

Late Edit 2021-06-06: I’ve noticed this document doesn’t cover IPv6 at all right now. I started to perform some tweaks to cover IPv6, but as my ISP has decided not to bother with IPv6, and won’t support Hurricane Electric‘s Tunnelbroker system, I can’t test any of it, without building out an IPv6 test environment… maybe soon, eh?

Read More
"map" by "Jason Grote" on Flickr

Documenting my Career Path

For something internal at work, I decided to sketch out how I got to doing the job I do today. And, because there’s nothing hugely secretive in that document (or, at least, nothing you wouldn’t already find out on something like Linked In), I figured I’d also put this on my blog… and I think it might be interesting if you’ve written something similar, if you’d share your document too.

I intend to make that a “Living Document” (like I do with my “What am I doing now” and my “What do I use” pages) that I update every time I think about it, and think they need a tweak. So, as a result, I’ve put them over on my “Career Path” page, which is not a traditional “blog post” and is in my sidebar.

Featured image is “map” by “Jason Grote” on Flickr and is released under a CC-BY-SA license.