LornaJane's Website

Using mitmproxy reverse mode for API testing

lornajane — Mon, 29 Jun 2026 20:06:00 +0100

mitmproxy is my preferred proxy for API testing these days. I'm using it mostly in reverse mode though, so I thought I'd capture my setup in case it's useful for anyone else. My main use case is to inspect the traffic coming into the API server and being returned, mostly when running tests against it. Where mitmproxy is typically used as a proxy to monitor traffic passing into/out of a client application, for this I'm concerned with the server's handling. Reverse mode lets me inspect and adjust the traffic as I go along. I start up the proxy, configure the tests to point to it instead of the actual server, and I'm all set.

Selectively ignore lines in git diff

lornajane — Wed, 04 Mar 2026 07:57:00 +0000

I have a things-as-code project that outputs mostly text-based formats, but a lot of them. To keep an eye on consistency, I rebuild all the outputs and dump them into a local git repository so I can very easily diff to spot any changes - which was fine until we added a build timestamp, so every file looks changed on every run! This post is about ignoring the matching line with git diff -I.

Git renames are not renames

lornajane — Wed, 28 Jan 2026 09:29:00 +0000

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. This week I had a spectactular git problem where merging one branch into another produced changes that didn't exist on either branch. Turns out, renaming directories in a monorepo with multiple almost-identical boilerplate documentation files comes with surprises...

Manage Diagrams in AsciiDoc on GitHub

lornajane — Sun, 25 Jan 2026 21:22:00 +0000

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. BUT what GitHub does not do is render the image types that asciidoc does so even though I'm working with asciidoc and PlantUML, and the asciidoc tools render those diagrams nicely in PDF and HTML output - GitHub's rendering doesn't. So here's a quick overview of how I handle those repositories.

Tag Kinds in OpenAPI 3.2

lornajane — Mon, 08 Dec 2025 08:32:00 +0000

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. In fact it is very useful to be able to tag endpoints with lots of different categories of data and so in OpenAPI 3.2, tags were enhanced to include an additional "kind" field so that different kinds of tag could be used.

Nested tags in OpenAPI 3.2

lornajane — Thu, 04 Dec 2025 20:53:00 +0000

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. If one level of organisation isn't enough for your API (and on bigger APIs I'd argue it shouldn't be) then the ability to indicate which tag is the parent of this tag will be a good feature to adopt when you upgrade your OpenAPI descriptions.

Notification Contexts Matter

lornajane — Sun, 16 Nov 2025 21:13:00 +0000

Like many of you, my days are dominated by notifications. Emails from project management systems, source control systems, calendar invitations, ticket updates, and message about messages on other platforms. I've noticed that some people use notifications as a power tool, while others seem blind to what happens when they do something. So this post is some tips that I've picked up along the way.

Quick local API docs with Scalar

lornajane — Wed, 17 Sep 2025 21:05:00 +0100

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. I also use a bit of glob expansion in my script to find the right folder, because I have a lot of APIs with long and formulaic directory names (TM Forum members know this story). I'm spinning up Scalar here as it's my current favourite just-works local API docs platform.

API Specificity with Overlays and Enums

lornajane — Mon, 21 Jul 2025 08:48:00 +0100

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. One of my favourite examples is to add enums where a standard interface cannot dictate the exact values, but in your own implementation it is very helpful to do so.

Safe Screensharing Setup

lornajane — Tue, 10 Jun 2025 17:32:00 +0100

In my time I've spent a LOT of time on screenshare, and I'm confident sharing my screen. Part of the confidence comes from maintaining a usage pattern that means I CAN confidently share my screen and rarely embarrass myself. After sharing some tips with a former colleague recently, I have tried to package up the best bits of that conversation and turn it into some tips to share.

Publish to GitHub pages with Sphinx

lornajane — Thu, 05 Jun 2025 09:59:00 +0100

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 to using Sphinx hosted on GitHub pages, so here are my setup notes.

Just Enough Docs

lornajane — Mon, 28 Apr 2025 18:12:00 +0100

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.

Right-Size Your RESTful API: More Flexibility Without GraphQL

lornajane — Wed, 26 Mar 2025 10:31:00 +0000

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.

Markdown/Mermaid output for OpenAPI Arazzo

lornajane — Wed, 12 Mar 2025 16:01:00 +0000

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 …

From HTTP to OpenAPI with Optic

lornajane — Mon, 17 Feb 2025 10:07:00 +0000

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.

Preview OpenAPI as HTML using Scalar

lornajane — Fri, 14 Feb 2025 14:49:00 +0000

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

Presenting with pdfpc

lornajane — Tue, 11 Feb 2025 12:08:00 +0000

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

Querying the GitHub GraphQL API

lornajane — Mon, 27 Jan 2025 12:48:00 +0000

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.

Save edits to OpenAPI as an Overlay

lornajane — Thu, 09 Jan 2025 12:18:00 +0000

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.

Run GitHub Actions on Subdirectories

lornajane — Tue, 07 Jan 2025 13:39:00 +0000

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.

OpenAPI Overlays to avoid API oversharing

lornajane — Thu, 12 Dec 2024 11:37:00 +0000

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!

Use multi-line values in GitHub Actions

lornajane — Mon, 25 Nov 2024 10:25:00 +0000

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.

How to structure and share code examples

lornajane — Mon, 18 Nov 2024 09:28:00 +0000

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!

Pretty-print JSON with jq

lornajane — Fri, 01 Nov 2024 17:20:00 +0000

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:

Open Standards for APIs

lornajane — Wed, 09 Oct 2024 08:21:00 +0100

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.

Lint APIs with Redocly CLI

lornajane — Mon, 05 Aug 2024 07:58:00 +0100

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.

API Description Pipelines

lornajane — Tue, 18 Jun 2024 21:54:00 +0100

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! This article shares my typical workflow, steps and chosen tools that might show up in an API description pipeline.

Checking Links in Docs-As-Code Projects

lornajane — Sat, 27 Apr 2024 17:48:00 +0100

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.

Reviewdog filter settings with GitHub Actions

lornajane — Mon, 25 Mar 2024 08:10:00 +0000

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.

Short tech writing style guide for developers

lornajane — Wed, 24 Jan 2024 09:18:00 +0000

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.

API Linting Levels

lornajane — Thu, 11 Jan 2024 00:05:00 +0000

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. The "best" ruleset depends entirely on your context, where you are in your API practice journey, and how much you want to invest in the API in question. I typically use a 4-levels model of API linting readiness, and I'm sharing them so that you can find yourself on the map and see where you might go from here.

Add OpenAI flags to OpenAPI descriptions

lornajane — Tue, 28 Nov 2023 09:48:00 +0000

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.

When to version bump your OpenAPI description

lornajane — Mon, 20 Nov 2023 13:10:00 +0000

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.

API docs previews with Redoc and Netlify

lornajane — Wed, 08 Nov 2023 09:18:00 +0000

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

Selective prose linting with Vale's glob switch

lornajane — Wed, 23 Aug 2023 11:55:00 +0100

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!

Visualise OpenAPI with Blockly

lornajane — Tue, 20 Jun 2023 12:57:00 +0100

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

Tips for better documentation with OpenAPI

lornajane — Mon, 12 Jun 2023 13:30:00 +0100

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.

Raising the Next Generation of DevRel

lornajane — Wed, 08 Mar 2023 20:42:00 +0000

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!

Improve Existing OpenAPI Descriptions

lornajane — Tue, 28 Feb 2023 18:04:00 +0000

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.

Manager's Secret Second Calendar

lornajane — Sun, 26 Feb 2023 16:33:00 +0000

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.

Generating a nice-looking PDF with Pandoc

lornajane — Tue, 03 Jan 2023 10:33:00 +0000

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!

Sphinx extensions for developer portals

lornajane — Tue, 08 Nov 2022 09:27:00 +0000

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 …

Internal DevRel: Colleague Enablement

lornajane — Mon, 26 Sep 2022 15:09:00 +0100

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.

Outline your writing to ease the creative process

lornajane — Mon, 11 Apr 2022 09:39:00 +0100

For most of my career I've been a software developer, but now I'm mostly a communicator. As a manager, I give the right level of detail to many different audiences, and I deliver that in words they can understand. As a Developer Advocate, I explain complex technical concepts in useful, memorable, and occasionally entertaining ways. However the best software developers are lazy and I'm still always looking for ways to get things done with less effort on my part! For writing, the best process I know feels like unnecessary overhead, but it's always worth it in the end so today I'm sharing my secrets: create an outline before you start.

Who are you writing that commit message for?

lornajane — Thu, 31 Mar 2022 20:55:00 +0100

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 …

Weekly Planning with Obsidian

lornajane — Wed, 16 Feb 2022 13:01:00 +0000

Keeping on top of tasks at work has been a work in progress throughout my career. However now I'm doing a more managerial role, I also need to keep track of all the meetings and preparation/followup work in my meetings. I find my daily log fills so many pages of notebook that I moved my weekly plan to a separate section - and then to my preferred digital notes tool, Obsidian. If you're interested in my setup, read on.

Keeping your finger on the (digital) pulse

lornajane — Tue, 15 Feb 2022 18:25:00 +0000

Whether you are building your own presence, or representing a brand or employer online, it's useful to know what people are saying! Keeping up with all those possible places you should look for news or mentions can be pretty laborious and when things are busy, it's difficult to keep up with this work unless you have some decent tooling in place. There are some great automation offerings around but here's my very basic strategy.

TL;DR a bookmarks folder in my browser to open a bunch of saved searches all at once.

Open Source and Business

lornajane — Sat, 12 Feb 2022 18:03:00 +0000

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. The talk, and these resources, are divided into sections.

View Open source is good for business on Notist.

About Open Source …

VSCode setup for technical writers

lornajane — Wed, 05 Jan 2022 14:23:00 +0000

I'm working almost entirely with docs-as-code setups for prose at work these days and while I do use vim for most of what I do, VSCode is increasingly in the mix. It's just about accessible enough with keyboard shortcuts and the command palette for me, and I thought I'd share the extensions I'm using and find helpful.

What Happened to your Blog?

lornajane — Sun, 12 Dec 2021 20:20:00 +0000

What happened to my blog? Nothing happened, I still blog ... except then I looked at my site the other day and realised, it's been a while.

Sphinx front matter and template variables

lornajane — Fri, 10 Sep 2021 21:47:00 +0100

I'm building a docs-as-code site at work at the moment (you can peek if you like https://developer.aiven.io) and working with ReStructuredText in this setup is new to me. One thing I really missed was the concept of front matter, which I'm not sure is even official or documented but seems to be reasonably widely supported (I promise to save the rant about markdown for another day). It took me a while to figure this out for Sphinx/rst but now I'm looking at it working, I had better write it down before I forget!

Use Database Connection Strings with Laravel 8

lornajane — Wed, 18 Aug 2021 08:56:00 +0100

I've been doing a lot of database stuff lately, and not much PHP, so when I returned to make my first Laravel project for a while, I had to check the docs to remind myself how some of this works. I noticed that the default approach to database credentials is still to use separate credentials for the host, port, and other variables. I'm using Aiven databases (because I work there and managed databases are great for demo apps as well as real ones!) which supply connection strings, but Laravel supports these too.

Hold Attention on the Virtual Stage

lornajane — Sun, 08 Aug 2021 22:37:00 +0100

How do I ensure that I keep my attendees' attention when I'm presenting virtually?

I don't.

Define Navigation Structure in a Sphinx Project

lornajane — Sun, 13 Jun 2021 19:11:00 +0100

As a newcomer to Sphinx, I found many things confusing, but the table of contents or "toc" configuration was the thing that almost made me change my mind and pick a different platform! I now have a setup that works pretty well, using Sphinx External TOC, so I thought I'd share my setup.

Considering Developer Relations as a Career Move

lornajane — Mon, 24 May 2021 11:02:00 +0100

I think that Developer Relations is a fabulous career, and I'm often asked how I got started, or how someone else could get started. There are a lot of people hiring for Developer Relations roles just now (including me!) so here are my tips.

There are so many different Developer Relations roles (called "DevRel") that I am definitely going to fall short of covering them all in any sort of detail! My own background is in Software Engineering, and I've mostly worked as a Developer Advocate since making the move into DevRel, so that's my context here.

Best Things About Developer Advocacy

lornajane — Mon, 26 Apr 2021 20:07:00 +0100

There are some excellent articles around about what a Developer Advocate does, but have you ever wondered WHY we do what we do? I tried to articulate this when chatting with another developer lately, and I'm still thinking about it! So I thought I'd write it down to share a little more widely why I love this strange, misshapen career as much as I do.

Measuring Repo Community Health with GitHub's API

lornajane — Wed, 14 Apr 2021 09:19:00 +0100

I'm on record saying that GitHub is your Landing Page and when I think about companies having open source profiles, I think about how many developers will have the first contact with them on GitHub. If it's a code example you're looking for then like it or not, GitHub is considered a search engine by many developers.

With that in mind, I wanted to look at GitHub's Community Health measure of the repositories I'm responsible for. You can view each repo's community page separately through the web interface (look under "Insights") but that's not especially scalable if you have a lot of projects to track.

From Spreadsheet to Database with ddlgenerator

lornajane — Mon, 22 Mar 2021 16:33:00 +0000

I've been using some fun open data sets recently but I'm more familiar with databases than with traditional data science formats (this one is CSV). Importing CSV into Postgres is fairly well-established, but you need a table structure to import into ... and I was looking at a CSV with 50 columns (for my post about exoplanets on the Aiven blog). Enter this neat utility: ddlgenerator.

Intro to RPi Pico with Mini Memory Game

lornajane — Mon, 08 Feb 2021 21:49:00 +0000

I am the proud owner of a Raspberry Pi Pico which is a dinky microcontroller from the lovely people at Raspberry Pi. I also have the RGB Pico Keypad Base, because my husband was buying something else from Pimoroni (3D printer filament, more on that another day) and we love them and ... here we are :)

I've tried to write down and link to the stuff I found useful along the way with this project, in case it helps you too. Well, no, really so I can come back to it next time I'm using one of these!

Lab Book Meets Bullet Journal

lornajane — Sun, 31 Jan 2021 21:39:00 +0000

I enjoy a productivity hack as much as the next person, and I'm often asked about my setup. My background is in engineering (I hold an MEng in Electronic Engineering from York) and recognise the legacy of the lab book in much of what I do. If you're new to the lab book concept, check out this excellent article on how to maintain one properly. My practice breaks a LOT of the lab book rules and is also heavily influenced by the Bullet Journal trend (if you have time to spare, the instagram #bulletjournal hashtag gives a prettier introduction), which is a way to combine the benefits of productivity and processing information by writing it. Today's post gives a quick tour of my process.

Digital Developer Relations: Past and Future

lornajane — Wed, 23 Dec 2020 09:24:00 +0000

I work in Developer Relations, or "DevRel", and 2020 was a strange year with travel restrictions that meant that the entire industry did everything online, or digitally. I see this as a very positive progression of the way we work as DevRel professionals, and I understand that might be controversial, but I'd like to back up my position so hear me out (and then let me know what you think!).

What's New in OpenAPI 3.1

lornajane — Mon, 14 Dec 2020 09:54:00 +0000

With OpenAPI 3.1 coming "soon", I gave a talk at APIDays Paris about what to expect. But I'm a great fan of the written word as reference so here's a written recap of what's in the next OpenAPI release.

Top features:
- Compatible with JSON Schema 2020-12
- Webhook support
- Many other minor improvements

Bystanders Guide to Repository Maintenance

lornajane — Fri, 04 Dec 2020 20:20:00 +0000

Today's post is about bystanders and open source. We sometimes have anxiety about doing things on "other people's" projects but the thing about open source is that those are not "their" projects, those are "our" projects, and they only exist because people other than their nominated gatekeepers chip in now and then.

Making SDKs a Value-Added Experience

lornajane — Mon, 16 Nov 2020 10:18:00 +0000

I've been working with SDKs quite a bit this year, simple ones that wrap a bunch of API endpoints. The best bits of these SDKs isn't just the delightful developer experience of using the clunky endpoints with the elegant SDK wrapping them. I mean, it is, but I already wrote about consistent and Delightful SDKs for Nordic APIs; today I want to cover the some of the "extra" things that make a big difference in the APIs.

DevContainers, VSCode and GitHub Codespaces

lornajane — Sun, 15 Nov 2020 13:31:00 +0000

I've seen quite a bit of chatter later about the GitHub Codespaces feature lately, and I have beta access to it so I thought I'd share my first impressions and make some notes of what I've tried that might be useful to others.

Ubuntu Command for Mic Mute with Pulsemixer

lornajane — Thu, 12 Nov 2020 17:27:00 +0000

One of the major problems I run into with video conferencing tools is how many of them are not at all accessible. I'm a keyboard-only user so if I need to hover a pointer in a particular area of the screen and then click an icon to mute ... then I can't do that. And if you mute me when I join because there are a lot of people here, then I can't participate at all. To work around this, I need a one-liner to mute (and unmute) my mic ... so here it is.

Keyboard-only Web Browser

lornajane — Thu, 22 Oct 2020 13:53:00 +0100

I haven't used a pointing device in over a decade, and I get a lot of questions about how I navigate the web using only the keyboard. The short answer is: Vimium and funnily enough, it's a productivity tool rather than an accessibility tool. Curious? Let me show you around!

Combine Multiple Field Tags in Go

lornajane — Wed, 21 Oct 2020 09:46:00 +0100

I work a lot with JSON APIs in my Go projects, so almost every struct has some field tags on it to translate AccountID into account_id and that sort of thing. Then one day I needed to load data from config using mapstructure and it took a few attempts with the search engine to find the syntax I needed, so it's here for next time I need it (or in case you need it too).

Adding Tables of Contents to Markdown

lornajane — Sun, 18 Oct 2020 20:34:00 +0100

Once any document gets over a certain length, a table of contents can be useful. I have a favourite markdown table-of-contents tool but it usually takes me a trip to the search engine to remember what it is! (tl;dr: github-markdown-toc )

Package Webpages as Apps with Nativefier

lornajane — Tue, 15 Sep 2020 11:22:00 +0100

There are a couple of specific web pages I use in separate windows from my other browser tabs, so I can always find them. However this quickly leads to a too-many-browser-windows problem. Instead, I have been turning them into basic standalone applications with a javascript tool: nativefier and I thought I'd share my recipes.

Create .desktop files for Ubuntu

lornajane — Sun, 13 Sep 2020 11:21:00 +0100

Having created a couple of .desktop files lately to make launching apps easier, I thought I'd write myself a quick reminder of what I did and how it works. If it's useful to you too, then great! I have one application in a weird path, and another that needs a specific environment variable set for it to work.

Sharing Screen and Camera from Android to Linux

lornajane — Mon, 17 Aug 2020 09:38:00 +0100

With all the video calls, twitch streaming and product demo work I've been doing recently, I've been building up a library of tricks for using my android devices within the video content I produce from my laptop, so I thought I'd share. I've worked remotely for many years but I think there's more of us not going back to the office any time soon, so strong video communication skills are important!

An Intro to Your ESP8266

lornajane — Sat, 08 Aug 2020 20:54:00 +0100

I've been using a microchip on my neopixel shelf project but I kind of set it up, changed one thing, and didn't look at it again until this week. I'd like to have my neopixels do something more interesting than one solid colour or another, so I needed to remind myself of what this thing is and how I do it. These are my notes, for my Ubuntu platform, but you're more than welcome to them!

Creating a Simple OpenAPI Spec

lornajane — Thu, 06 Aug 2020 13:44:00 +0100

Having API descriptions in your workflow is a game-changer, but how do you get from nothing to a functioning spec in the first place? I recently made a very simple spec for a very simple API, and thought it might make a good example for anyone looking to create a spec for the first time. OpenAPI specs are very verbose so this very tiny API makes quite a manageable example!

Using Environments in Postman

lornajane — Thu, 23 Jul 2020 16:55:00 +0100

I'm using Postman more lately and showing off the Environments feature really often. I really like this feature for giving easy ways to handle values I use frequently, but it seems to be a bit of a hidden gem, so I thought I'd write about when I find it useful, in case you do too!

Planets and Webhooks: a simple Flask app

lornajane — Wed, 22 Jul 2020 14:50:00 +0100

As a Developer Advocate for an API company, I spend a lot of time talking about APIs and webhooks and HTTP in general. Recently I've been focussing on HTTP tools, but I really wanted a very simple example API that I could use that would return JSON but really let me focus on the tools, not the API. So I created a "Planets and Webhooks" API with a couple of GET endpoints to return JSON data, and another endpoint to receive and log incoming webhook data.

Neopixel Shelf

lornajane — Sat, 18 Jul 2020 17:47:00 +0100

In these days of video calling in place of any other social contact, I've seen a lot of excellent video backgrounds. Perhaps I'm old-fashioned but I went the traditional route, and set up my computer close to a wall (so you can't see the mess in the room) and added a nice pinboard behind me. I looked a bit flat against the wall though, so I did what anyone else would do ... and built a handmade wooden shelf with neopixels in it!

Add a Screenshot Button to Streamdeck with Golang

lornajane — Mon, 06 Jul 2020 10:09:00 +0100

I'm the proud owner of a Streamdeck XL but as an Ubuntu user, the tool support isn't great. There's a Python library that gives a bit of a GUI but I found it hard to use and I'd have needed to put each piece of functionality as a commandline script that this program could call. Instead, I am using go-streamdeck to create a custom application - and I'm having fun! Today's example adds a single button that runs a command to take a screenshot.

Accessing Nested Config with Viper

lornajane — Thu, 25 Jun 2020 21:28:00 +0100

I'm writing a Go application that glues together a bunch of other things, so it has a whole bunch of basically unrelated config, dumped in a yaml file. I was struggling a little with this non-standard use of Viper but actually, it does everything I needed. And, presumaby, more besides. I thought I would put some examples here to show how to handle this.

Use a Local Version of a Library in Go

lornajane — Mon, 15 Jun 2020 09:51:00 +0100

I have a couple of projects in Go where I need to work with a branch that isn't the released version of a library that my code depends on. This happens when I'm the developer of the library and an application to use it, or when I'm a contributor to the library so I have my own fork and will want to check out branches to submit or test patches. Go has a pretty need way to allow this: using the replace keyword in the go.mod file.

OBS Studio, Ubuntu 20.04 and a Wacom Tablet

lornajane — Sun, 31 May 2020 20:31:00 +0100

When I upgraded my computers to Ubuntu 20.04, I noticed a weird problem with OBS when using an old Wacom Bamboo tablet (because, have you ever tried to use OBS without a pointing device?). I couldn't actually click anything! The pointer seemed to be ... pointing to the wrong place …

Eye Contact Owl

lornajane — Tue, 26 May 2020 20:11:00 +0100

I don't post as much handicraft on this blog as I used to (it's mostly on my instagram account with fewer words now), but I wanted to share my new handmade owl. He solves a genuine problem: how to make eye contact with your webcam.

Custom OpenAPI Style Rules with Spectral

lornajane — Thu, 21 May 2020 15:54:00 +0100

Edit: There's a newer post on this topic using Redocly CLI.

I work quite a bit with OpenAPI specs and with lots of specs and lots of collaborators, keeping the specs all functional (never mind tidy, consistent, or other dreamwords) is a challenge! We use spectral to check our specs, both when we work on them and in the build process. Spectral is great but it has Opinions(TM)!

For most users, running Spectral out of the box gives quite a lot of output even on an otherwise valid spec. I do think the default ruleset for Spectral is pretty good, but every situation is different so having your own ruleset to use is a good idea. This post shows how to use a ruleset and some examples.

The python-is-python2 package on Ubuntu Focal Fossa

lornajane — Fri, 24 Apr 2020 19:15:00 +0100

I did a fresh install of Ubuntu 20.04 Focal Fossa on my laptop, and was surprised at what happened when I went to install python:

$ sudo apt install python
Reading package lists... Done
Building dependency tree
Reading state information... Done
Note, selecting 'python-is-python2' instead of 'python'

Um, what?

It …

A First Netlify Function in Golang

lornajane — Wed, 15 Apr 2020 11:20:00 +0100

I love all things serverless, and Netlify Functions is a neat and convenient way to access AWS Lambda. I do also love AWS Lambda but it's so powerful and flexible that creating something like a webhook receiver can be hard going by the time you have all the permissions and API Gateway setup sorted out - for a simple webhook receiver, Netlify functions is a nice and easy way to get going. Best of all: it supports Golang but the docs are very JS-heavy so I am writing my notes here in case I need to refer back to them some day.

Wget Direct to S3 with Golang Streams

lornajane — Wed, 08 Apr 2020 16:30:00 +0100

One thing I find very elegant about working with golang is that it is very open minded about where data is flowing in from or going out to. I recently built an application that downloaded an audio file from one location and pushed it to s3 - and golang makes it very easy to do that without needing to write an intermediate file and then upload that. Here's my code, in case I need to do this again some day :)

HTTPMock for Testing a Golang API Client

lornajane — Mon, 30 Mar 2020 20:08:00 +0100

I'm working on an API client for some Nexmo APIs and having tests to work through the various responses that the API can return and check that it does what I expect has been very handy so I thought I'd share my thoughts. I've got a bit of a head start here too since the OpenAPI specs have example responses in them that I can grab and feed to the mocking tool I'm using in my tests!

Remove Accidental Content from Git Commit

lornajane — Sun, 15 Mar 2020 20:24:00 +0000

When I teach git I try to show loads of good practice about how to inspect what's staged before commit, etc etc. Good practice is good of course, but knowing how to undo a mess you created is better - and mistakes will happen. For example, accidentally including a node_modules directory in your otherwise excellent and useful commit. This post will walk you through how to fix the problem without losing any of your work.

Teach Your API Test Platform to Send Callbacks

lornajane — Tue, 18 Feb 2020 15:50:00 +0000

I already wrote about using Prism as an API test platform but I didn't include an example with callbacks so this post is to fill that gap! If you didn't read the previous post, the tl;dr is that Prism is a nodejs open source tool that can take your OpenAPI specification and then do an impression of your live API, validating the API calls sent to it and responding with the example data described in the spec. It can also follow up the API response and send an HTTP request of its own to mock the callbacks described in your OpenAPI spec.

Make Thumbnails of PDF Pages with ImageMagick

lornajane — Sun, 16 Feb 2020 15:06:00 +0000

All my talk slides are PDF - I use rst2pdf to transform text-based ReStructuredText content into presentation slides. With all these PDFs hanging around, it can be very handy to have them as thumbnails. I use the images both in the printable speaker notes that I produce (and I should blog that too now I've mentioned it), and to share on twitter - especially the resources slide that everyone photographs! My image file is much more readable than your cameraphone picture in terrible lighting :) So here's my script for thumbnails in case you want to do the same; most presentation tools will export to PDF if you're not already working in that format.

Instant Test API Platforms with Prism

lornajane — Thu, 23 Jan 2020 11:17:00 +0000

I've been writing a bit about OpenAPI lately and I realised that I didn't share how I'm creating local, test versions of production APIs to work with while I develop new client code or test SDK features. The recipe is simple: you will need an API spec, the excellent open source tool Prism and an HTTP client. Mix it up and be ready to change your API development workflows forever.

Grab Annotations from a PDF with pypdf2

lornajane — Wed, 15 Jan 2020 20:37:00 +0000

If you've noticed a lot of PDF content around here lately, that's because I work with PDF a lot! Most of all, all my slide decks are in PDF and in the last year or so I've started using speaker notes in my presentations. Yes, this means that if you saw me speak in the first ten years of my speaking career, that was without speaker notes.

There are some situations where I don't have access to my speaker notes. Usually this is a good reason, such as I have mirrored my displays so I can demo or play a video without fiddling with my display settings in the middle of a talk. Sometimes, it's because something bad happened and I'm presenting from someone else's machine or a laptop that's completely off stage and I only have the comfort monitor. For those situations I use a printed set of backup speaker notes so I thought I'd share the script that creates these.

Raspberry Pi SenseHat Night Clock

lornajane — Sat, 28 Dec 2019 09:36:00 +0000

I recently upgraded my smartwatch and the new model needs charging daily (whether that's really an upgrade is a separate discussion!) so I drop it on the charger by my bed overnight. As a result, I can't tell the time if I wake up in the night which is only annoying because I don't know if it's midnight or if the alarm is going to go off in ten minutes! So I made myself a colourful fuzzy time clock with a raspberry pi and a SenseHat that were lying around in my office.

Counting Duplicate Commit Messages

lornajane — Mon, 16 Dec 2019 16:24:00 +0000

When chatting about source control good practice the other day, I got a question about repeated git commit messages. In general, I would always advise that the same commit messages appearing multiple times in a project's history is a definite red flag - and if I'm responsible for that repository I will probably make fun of you for doing it.

Ruby for non-Rubyists with Snap

lornajane — Mon, 07 Oct 2019 09:52:00 +0100

I'm an Ubuntu user and I enjoy most server-side scripting languages but I haven't done much Ruby and I never get the feeling that Ruby is pleased to see me when I do. Something is always out of date or has an incompatible dependency or ... and since I don't use …

Sniglet is a Font for Avoiding Font Loading Mistakes

lornajane — Mon, 16 Sep 2019 20:45:00 +0100

I am not a designer, nor will I ever be. Things look perfectly fine to me a very long time before they look OK to anyone else! Along with that, I don't always find it easy to tell fonts apart. I can do serif-ish and sans-ish but if the fixed-width font has serifs on it I sometimes miss that detail if I'm not looking for it - which also means that I have no idea if I've loaded the fonts I was thinking of or not.

To get around this, I test everything by switching the font to Sniglet from the League of Moveable Type. It's ... umistakable!

OpenAPI Description using API key and secret

lornajane — Thu, 15 Aug 2019 18:10:00 +0100

I've been working on a few OpenAPI descriptions of APIs lately, and really enjoying the benefits they bring. In particular the ability to import into Postman as a collection I think is a "killer feature" for APIs looking to get developers up and running quickly. The catch? I found that an API that needs an API key and secret, or a username and password/token, is supposed to be described with multiple security schemes - but this does not play nicely with tools like Postman.

The Laravel Synchronous Queue

lornajane — Mon, 20 May 2019 15:43:00 +0100

Using queues for asynchronous processing is one of my favourite tricks for offloading hard work from web servers. When working with Laravel recently I was pleased to find that it supports beanstalkd out of the box. I've got opinions about frameworks with Opinions but I did find one thing I really liked in the way Laravel uses queues: the sync queue option that runs your queue synchronously on your development platform so you can develop and debug your work, then switch the queue platform you use later.

The First Thousand Blog Posts

lornajane — Tue, 30 Apr 2019 09:51:00 +0100

This is the 1000th post on https://lornajane.net. People ask "how do you even do that?" and the short answer is "start in 2006", but the long answer isn't all that long.

Handy Beanstalkd Admin Console

lornajane — Mon, 08 Apr 2019 09:13:00 +0100

I've been building apps with queues lately and mostly using beanstalkd as my queue because it is very simple, very fast and on my platform it is [apt install beanstalkd] -easy to install. I have also been using a handy web interface for beanstalkd which I like so much that I felt I ought to share! It's beanstalk-console, which is a PHP-based web interface to one (or many) beanstalkd servers.