Category Archives: tech

12 Dec
2024

OpenAPI Overlays to avoid API oversharing

Most APIs aren’t perfect. By design they are long-lived and may serve many audiences. I see a lot of organisations maintaining multiple versions of APIs, or simply not documenting some of the endpoints to avoid them being included in the published documentation and confusing users. The problem of API redaction is a real one in most organisations, and it goes unsolved or is solved in a way that causes ongoing friction. I’ve helped a few API projects to solve this problem with the new OpenAPI Overlay specification so I thought I’d share! Continue reading →
25 Nov
2024

Use multi-line values in GitHub Actions

I created an action that needed a rich Markdown value in it, because it’s our weekly meeting agenda template which is formatted for humans with links and paragraphs and things. The Action syntax produced errors when trying to add the content directly to the action, but I got it to work by putting the content into the file, and using the file contents as an environment variable. That’s really the punchline of this post, but read on if you would like more details and some examples. Continue reading →
18 Nov
2024

How to structure and share code examples

Writing for technical audiences often means sharing code in one form or another. If the code is only for illustration purposes, then it can be included in the article for observation. But if the code is useful or reusable by your readers, then you need a way to make it available to them. I’ve seen a few questions on this recently (shout out to the DevRel Collective slack for a brilliant discussion AND nagging me to write it up as a post!), so I’m sharing my experiences on how to publish and maintain code in sane ways! Continue reading →
01 Nov
2024

Pretty-print JSON with jq

Wrangling some document conversion the other day, I ended up in a situation where I had the JSON I needed, but in a completely unreadable format. Luckily, this problem is very easily fixable …. when you know how. So today’s post is a quick recap on how I did that using jq, a very handy command-line tool for working with JSON. For the impatient, here’s the command:

cat posts.json | jq "." > better.json

In this post we’ll look at the data I started with and what the different bits of the command to do help. Continue reading →

09 Oct
2024

Open Standards for APIs

I work or have worked with APIs of all sorts of standards, sometimes many standards at once – or none. Each standard exists for a purpose and might be a great fit, or a terrible fit for other purposes. Today’s post is a recap of some of the common API standards around and what you need to know about each one. Continue reading →
05 Aug
2024

Lint APIs with Redocly CLI

API governance needs good tooling, and rules that fit – so today’s post covers both.

Fun fact: I work at Redocly and had used the tool for years, but recently realised that I have a post about a different tool in the archives of my blog, but no Redocly post. So here’s the Lorna-recommended version of OpenAPI linting with Redocly CLI. Continue reading →

18 Jun
2024

API Description Pipelines

Working on API tools, I get to see inside lots of different organisations’ API projects and processes. Every scenario is different, but a common theme is that many companies use a more complicated API description workflow than you see in conference slide decks! Without sharing any one organisation’s secrets, this article shares a rundown of some typical steps that might show up in an API description pipeline. Continue reading →
27 Apr
2024

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 →

25 Mar
2024

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 →
24 Jan
2024

Short tech writing style guide for developers

Style guides are vital to successful publishing projects, but they are usually too extensive for casual contributors. After running a number of projects with developers rather than specialist documentarians as the main contributors, I’ve started using a short-form style guide, short enough to be read and used by people who don’t spend as much time thinking about these things as a full time writer does. The main version is published on GitHub, but I’m also sharing the current version here. Continue reading →