Checking Links in Docs-As-Code Projects

Creating content requires accuracy as well as creativity and the ability to deliver. Working with docs-as-code gives a strong foundation and structure to work within, and means there’s a clear workflow where automation can be added to help us with the easy stuff, such as “do all these links work?”.

I really appreciate having the extra confidence and support of these types of tools, and having implemented them on multiple projects at this point, I thought I’d share my advice for anyone looking to do the same. Continue reading

Reviewdog filter settings with GitHub Actions

Reviewdog is a tool to use with GitHub actions for applying review tools in your CI. I use it with Vale, and it’s really good. One thing that has tripped me up multiple times is that by default, it only applies the checks to the changes in the pull request, not to the whole project. So when you add something like Vale, which is a prose linter, it only checks … the workflow file you just added! I always forget that it works this way, and how to change it, so I’m pasting some examples for future reference. Continue reading

Add OpenAI flags to OpenAPI descriptions

With OpenAI’s new Actions feature allowing you to get a GPT that uses your own API, many new doors are open. However giving an AI an access token the keys to your API and telling it to have fun may lead you to realise that one of the doors available leads to the empty lift shaft of overwritten data, or the bottomless well of cloud bill shock. To reduce the risks, OpenAI supports an extension x-openai-isConsequential that you can add to your OpenAPI description, to indicate which endpoints should not be called without a human confirmation step.

I’m not doing much with OpenAI right now, but I do plenty with OpenAPI and the question “how do I add this field to my existing API description?” is one that I can answer! What’s more, you can use the advice in this post to add other extensions or additions to your OpenAPI descriptions using Overlays, this advice isn’t OpenAI-specific, but it’s used in the examples. Continue reading

When to version bump your OpenAPI description

I’ve heard a variety of bad advice (and some untruths!) regarding how to version your OpenAPI description lately. Rather than dig into those, instead I’ll share my opinion on how I like to version API descriptions in my own projects. Every API project is different, but perhaps there’s something here that can help your project too. Continue reading

Manager’s Secret Second Calendar

Employees expect a lot from their managers, and as managers we do our best to meet those expectations. However most managers are only human (I’ve met a few that I had doubts about), and so it can be difficult to get absolutely everything right absolutely all the time. I’d like to share a tactic that I learned from another manager around the time that I took my first line manager role, that I think really helped me to at least give the impression that I knew what was going on: a second calendar, visible only to you, with key dates in. Continue reading

Who are you writing that commit message for?

I read a lot of commit messages that make me wonder who the committer had in mind when they wrote it. If you don’t read commit messages yourself, I think that can make it even more difficult to think about who the audience is, or when someone would be reading those entries. Perhaps you’re writing for nobody, or work in a team that doesn’t value the metadata that a single sentence written in the moment can deliver.

Next time you write a commit message, try some of these suggestions as your imaginary audience:

  • Yourself, next week, when you finally get back to working on this thing and can’t remember where you were up to
  • Yourself, when you get a pull request review and can’t remember which commit something is in that needs to be removed
  • Yourself, debugging how this ended up like this, 6 months from now
  • Your colleague, eyeballing your work to see how you are getting on

Personally, I think of it as a note to myself. Like an alibi, if someone asks you what’s already been done, or what this commit that removes one specific line from a long config file. Yes, I worked as a git consultant for a while, the delete-a-single-line with the commit message “Fixed” is always the culprit!

Further reading: https://cbea.ms/git-commit/

VSCode setup for technical writers

I’m working almost entirely with docs-as-code setups for prose at work these days and while I do use vim for most of what I do, VSCode is increasingly in the mix. It’s just about accessible enough with keyboard shortcuts and the command palette for me, and I thought I’d share the extensions I’m using and find helpful. Continue reading

Ubuntu Command for Mic Mute with Pulsemixer

One of the major problems I run into with video conferencing tools is how many of them are not at all accessible. I’m a keyboard-only user so if I need to hover a pointer in a particular area of the screen and then click an icon to mute … then I can’t do that. And if you mute me when I join because there are a lot of people here, then I can’t participate at all. To work around this, I need a one-liner to mute (and unmute) my mic … so here it is. Continue reading

Combine Multiple Field Tags in Go

I work a lot with JSON APIs in my Go projects, so almost every struct has some field tags on it to translate AccountID into account_id and that sort of thing. Then one day I needed to load data from config using mapstructure and it took a few attempts with the search engine to find the syntax I needed, so it’s here for next time I need it (or in case you need it too). Continue reading