Category Archives: tech

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 →
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 →

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

Sphinx extensions for developer portals

I’ve been gushing about docs-as-code, but realised that I haven’t shared many hands-on tips for actually building different types of sites in this sort of toolchain. I’ve been mostly using Sphinx which generates much better-looking documentation than its website suggests. It’s a python-based static site generator, with a thriving community and lots of great extensions. Today I thought I’d share the extensions I use the most for developer portals (like the Aiven docs, one of my work projects and the source of the screenshots in this post) and what I like about them. Spoiler: may contain a theme as well as the extensions.
26 Sep
2022

Internal DevRel: Colleague Enablement

I work in Developer Relations for a very technical company (Aiven), and I usually describe my job as half explaining my employer’s technology to developers, and half explaining developers to my employers. However in the last year or so, I’ve realised that there is a variation on this theme that is impactful for my internal colleagues: explaining technology and developers to people who are experts in something else. I work with specialists in various aspects of sales and marketing (DevRel reports into Marketing) and my colleagues are genuinely curious to know more about the domain we work in! I thought I’d share more about how I enable my colleagues, and why I think it works for us. Continue reading →
31 Mar
2022

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/