05 Jun
2025

Publish to GitHub pages with Sphinx

I’m a big fan of docs-as-code for more or less any type of content publishing, but I’m less of a fan of Jekyll, the default tool used in GitHub pages. I also prefer ReStructuredText over Markdown as a markup format, so Sphinx is definitely on my shortlist of SSGs (Static Site Generators) for my projects. I recently switched the rst2pdf docs over to using Sphinx hosted on GitHub pages, so here are my setup notes. Continue reading →
28 Apr
2025

Just Enough Docs

Too many open source projects suffer from inadequate documentation, and that hurts their adoption, their communities, and puts more burden on maintainers. Many people who create open source software don’t see see themselves as writers, but today I’m sharing tips for documenting open source projects without it needing to take up a huge amount of time to get something published and ready for (docs) contributions. Continue reading →
26 Mar
2025

Right-Size Your RESTful API: More Flexibility Without GraphQL

If you publish a RESTful API and there are situations when you need less (or more!) detail in the API responses from your API – then this post is for you. When I run into this with the teams I advise, the initial problem statement usually arrives more like “We need to move to GraphQL”, but this is a solution, not a problem to solve. The problem usually turns out to be either or both of:

  • the API responses are simply too large for some of the clients or uses cases, users need to select just the fields they want
  • the API doesn’t have enough information in the response payload for this client or use case, users need to choose to include nested data

GraphQL is one way to achieve these things, but this post is about the RESTful way to provide the right level of detail in an API response. Continue reading →

12 Mar
2025

Markdown/Mermaid output for OpenAPI Arazzo

API reference documentation changed the way we built integrations, and eventually became part of the driving force for OpenAPI adoption and all the good tooling that flowed from it. As a developer experience specialist, I spend a lot of time thinking about how human users can work with the technical assets in a project. HTML-format API reference documentation does a great job of building that bridge when working on OpenAPI projects, but now I’m using Arazzo and it’s a very new standard with not nearly as many tools available for that format yet – so I built one. –
17 Feb
2025

From HTTP to OpenAPI with Optic

I’ve been using Optic’s CLI, an OpenAPI tool that does a bunch of things including diffing OpenAPI descriptions and comparing HTTP traffic with OpenAPI. My use case was an established API that didn’t have an OpenAPI file yet – using Optic we could create one as a starting point, and then move to a design-first workflow to make the changes that I was there to help with. For this blog post, I’ve used the example of https://api.joind.in as an excellent representation of an API still in use, but without an OpenAPI file and not built with code that a code generator would recognise. Continue reading →
14 Feb
2025

Preview OpenAPI as HTML using Scalar

The API DevTools space is alive and well with lots of new and exciting products popping up all the time. I’ve been especially impressed by the new tools in the docs space, but some of the options are less practical for use as quick human-friendly OpenAPI renderings or previews to use during API development. My current favourite in this space is Scalar because I can get an HTML file to easily include in a build or share with others. It’s a bit of a hack though, so I thought I’d share… Continue reading →
11 Feb
2025

Presenting with pdfpc

My slide deck tool ( rst2pdf ) produces PDFs, and I use pdfpc to present the PDF slides. It shows the current and next slides, my notes, a timer, and it probably does other things too that I don’t use! I’ve used it for years but it was really designed for “in real world” presenting with one or two screens. Recently I discovered it also supports some great options for remote presentations, but I had to look up how to do that so here are my notes (mostly in case I need to look it up 1 minute before I go on stage again!!). Continue reading →
27 Jan
2025

Querying the GitHub GraphQL API

In a recent project around open source contributors, I wanted to take a look at which projects a particular user (actually a few of them, but I wrote a wrapper to repeat the process for each handle) maintains. GitHub doesn’t show this maintainer relationship, so instead I used the v4 GraphQL API and looked at pull request comments on repositories that the user has access to. I’m sharing my query and the Python script I used to make the API calls to. Continue reading →
09 Jan
2025

Save edits to OpenAPI as an Overlay

For teams that generate OpenAPI from their codebase, there’s a tough choice between maintaining rich and extensive content such as Markdown descriptions and examples in codebase annotations, or in making those changes to the generated file – and then losing them when the code changes and the file is regenerated. The new OpenAPI Overlay Specification defines a format for storing updates to an OpenAPI document, and there’s a new generation of tools to make it easy to do, so let’s take a look. Continue reading →
07 Jan
2025

Run GitHub Actions on Subdirectories

I come across a lot of “greedy” GitHub Actions, where automation is running across a whole project instead of only on the parts that are relevant. Examples might be code linters that report problems with documentation folders, or the inverse of that. It’s especially problematic in monorepos where we probably want to use the same tool when we’re doing the same task for different subfolders, but that tool might not make sense to run everywhere. Continue reading →