LornaJane's Website

Best practice in APIs always includes the advice to include examples.

This blog has been online for 20 years, and I've tried to spend a lot more time writing content than fiddling with the toolchain or theme for it, because too many blogs never see the light of day because the theme is somehow never ready.

mitmproxy is my preferred proxy for API testing these days.

I have a things-as-code project that outputs mostly text-based formats, but a lot of them.

I consider myself pretty git-confident, I've worked with it a lot, taught it, been a git consultant, run engineering and various things-as-code teams.

I use a lot of asciidoc these days for work documentation (and I love it) and I've been so happy that GitHub renders it when you view a repository in the web browser, just like it does for Markdown and ReStructuredText.

OpenAPI tags have always been annoying: user-supplied arbitrary data for endpoints should be a fabulous feature - but the documentation tools seem to think that tags are only for them so it becomes more difficult to use tags for other purposes.

OpenAPI has always had support for simple tags, but the OpenAPI 3.2 release brought in some serious tag upgrades including a summary field, a "kind" field with registry, - and the ability to nest tags which is the focus of today's post.

The entry level here is to use a correct and meaningful title for the issue/pull request/ticket.

Today I'm sharing a quick-and-dirty script to take an OpenAPI description, spin up a docs server locally, and copy the URL into your clipboard.

The more I work on API standards, the more I realise how few teams understand that they can adopt the standards and, without breaking any contract, adapt them to make a strong interface for their own application.

In my time I've spent a LOT of time on screenshare, and I'm confident sharing my screen.

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.

Too many open source projects suffer from inadequate documentation, and that hurts their adoption, their communities, and puts more burden on maintainers.

If you publish a RESTful API and there are situations when you need less (or more!)

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.

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.

The API DevTools space is alive and well with lots of new and exciting products popping up all the time.

My slide deck tool ( rst2pdf ) produces PDFs, and I use pdfpc to present the PDF slides.

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.

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 losi…

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.

Most APIs aren't perfect.

The wider context is that we use GitHub Discussions to plan meeting agendas.

Writing for technical audiences often means sharing code in one form or another.

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.

I work or have worked with APIs of all sorts of standards, sometimes many standards at once - or none.

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

Working on API tools, I get to see inside lots of different organisations' API projects and processes.

Creating content requires accuracy as well as creativity and the ability to deliver.

Reviewdog is a tool to use with GitHub actions for applying review tools in your CI.

Style guides are vital to successful publishing projects, but they are usually too extensive for casual contributors.

I've been thinking about API linting lately, partly because I work on a tool for API linting in my day job, and partly because I get quite a lot of questions from teams wanting to improve their API quality.

With OpenAI's new Actions feature allowing you to get a GPT that uses your own API, many new doors are open.

I've heard a variety of bad advice (and some untruths!)

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.

Vale is an open source CLI tool for linting prose (if you're not linting prose yet, why not?

Giving talks about OpenAPI often means lots and lots of slides of YAML.

I love documentation, which is supposed to be rare for software engineers.

Developer Relations isn't new, but it's also broad, ill-defined, and constantly evolving.

I'm a firm fan of a design-first approach to building APIs, and advocate for it at every opportunity.

Employees expect a lot from their managers, and as managers we do our best to meet those expectations.

Pandoc is one of my favourite tools in the world.

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

For most of my career I've been a software developer, but now I'm mostly a communicator.

I read a lot of commit messages that make me wonder who the committer had in mind when they wrote it.

Keeping on top of tasks at work has been a work in progress throughout my career.

Whether you are building your own presence, or representing a brand or employer online, it's useful to know what people are saying!

This collection of resources accompanies my keynote talk "Open source is good for business", since it's easier to access links on a web page than in a slide deck.