28 Nov
2023

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 →

20 Nov
2023

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 →
08 Nov
2023

API docs previews with Redoc and Netlify

I talk to a lot of people about their API lifecycles and processes, and one thing that has value in almost every case is immediate documentation preview for all updates to an OpenAPI description. The time it takes to set it up (about ten minutes now I know what to do) is an investment that makes every future change easier to propose, review, and accept. Here’s my recipe for open source OpenAPI documentation using Redoc (disclaimer: I work for Redocly, who publish Redoc) with the files pushed to Netlify for hosting (but it’s HTML, so really any hosting will do and you should feel free to adapt the instructions for your preferred platform, and then share them in the comments). Continue reading →
23 Aug
2023

Selective prose linting with Vale’s glob switch

Vale is an open source CLI tool for linting prose (if you’re not linting prose yet, why not? I never want to go back). I typically use it for everything, locally and in CI, and it’s especially valuable now I’m working for a company that uses US English. You’d think that most of the challenges would be caused by the majority of non-native English language contributors? Nope, most of the chaos comes from the token Brit :)

I ran into one challenge though where I didn’t want to enable Vale for everything: a large internal documentation repo. This is the catch-all of things we should share with one another and like most internal company documentation sites, there is a lot going on. I assembled a very minimal set of Vale rules and still the first pass netted me over 10k errors. Luckily, Vale has a --glob option, but it took me a while to find how to exclude multiple files and directories using it, so here’s the example for future-me, and anyone else who needs to see it! Continue reading →

20 Jun
2023

Visualise OpenAPI with Blockly

Giving talks about OpenAPI often means lots and lots of slides of YAML. In fact, one of my talks even contains a “warning, contains yaml” slide! If you aren’t a professional yaml developer, it can be difficult to digest and learn from, and so I wanted to do better. The various elements are nested inside one another, and so I had this idea to build a representation of OpenAPI using Blockly (the tooling also used for Scratch, if you’ve seen that).

Showing tags with descriptions
Continue reading →

12 Jun
2023

Tips for better documentation with OpenAPI

I love documentation, which is supposed to be rare for software engineers. I am pretty sure that loving documentation is actually very common, but not very cool and so few people admit to it! I love reading good docs, and so I love writing them too. Between hanging out in the Write the Docs community, and recently being at the APItheDocs conference, I’ve answered a bunch of questions about getting good documentation from an OpenAPI document, so I thought I’d round them up in case it’s useful. Continue reading →
08 Mar
2023

Raising the Next Generation of DevRel

Developer Relations isn’t new, but it’s also broad, ill-defined, and constantly evolving. It’s difficult to keep your own skills up to date, never mind coping with a whole team full of people and constantly creeping industry scope. The required combination of specialist and generalist skills to be successful is any of the Developer Relations and allied roles is extensive, and it’s easy to feel overwhelmed and end up coasting being just-good-enough at things but never feeling mastery.

As an individual contributor, manager and general DevRel presence over the years, I’ve developed some tactics both for myself and my team, and I’d like to share them in case they’re useful to others. Also since I’m moving to a less DevRel role, writing this down while I can still think about it! Continue reading →

28 Feb
2023

Improve Existing OpenAPI Descriptions

I’m a firm fan of a design-first approach to building APIs, and advocate for it at every opportunity. Repeatedly. Design-first means that an API change starts in the OpenAPI description, gets reviewed and approved by the stakeholders, and then gets built afterwards.

I also live in the real world, where OpenAPI descriptions get generated from existing codebases, and engineering teams lack either the knowledge or the enthusiasm to modernise their processes. With a generated OpenAPI description, everything else that OpenAPI enables is likely to be disappointing, because the description only contains the information that was in the serverside code, and if you’re lucky some comment metadata. Enter OpenAPI Overlays, a way to describe alterations to an existing OpenAPI description that can be reapplied every time that description changes. Continue reading →

26 Feb
2023

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 →
03 Jan
2023

Generating a nice-looking PDF with Pandoc

Pandoc is one of my favourite tools in the world. If you haven’t come across it before, it converts between more or less any two document formats. I use it a lot with MarkDown and ReStructuredText so that I can produce content efficiently and then share it in a way that looks nice, but also to get word documents into cleaner formats. However the PDF output has always looked a little bit … dated? (this is rich from an rst2pdf maintainer I know!) and I was recently delighted to find some tricks that resulted in a better PDF. I’m sharing them here, so I can find them again in the future; you are welcome to use them too, of course! Continue reading →