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

Using Environments in Postman

I’m using Postman more lately and showing off the Environments feature really often. I really like this feature for giving easy ways to handle values I use frequently, but it seems to be a bit of a hidden gem, so I thought I’d write about when I find it useful, in case you do too! Continue reading